Hoist React

https://github.com/xh/hoist-react
Admin
Hoist React is the client-side implementation of a full-stack UI development framework for...
Tokens:408,925
Snippets:2,932
Trust Score:7.6
License:Apache-2.0
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Setup file that installs the app fake

Source: https://github.com/xh/hoist-react/blob/develop/docs/unit-testing.md

This setup file imports and installs the app-specific fake, which seeds the server state that every client receives.

```typescript
// src/test-support/setup.ts
import {hoistCore} from '@xh/hoist/test-support';
import {installMyAppFake} from './myAppFake';

installMyAppFake(hoistCore);
```

--------------------------------

### Install custom services in AppModel.initAsync

Source: https://github.com/xh/hoist-react/blob/develop/svc/README.md

Shows how to install custom services during app startup. The first call installs services concurrently, the second chains for ordered initialization when services depend on earlier ones.

```typescript
class AppModel extends HoistAppModel {
    override async initAsync(ctx: InitContext) {
        // Install custom services - all initialize concurrently
        await XH.installServicesAsync([TradeService, PortfolioService], ctx);

        // Chain calls for ordered initialization (when services depend on earlier ones)
        await XH.installServicesAsync([ReportService], ctx); // Can now use Trade/Portfolio services
    }
}
```

--------------------------------

### Basic Grid Setup with GridModel

Source: https://github.com/xh/hoist-react/blob/develop/cmp/grid/README.md

Basic grid setup using GridModel with a store, columns, and initial sort. The grid component is rendered with the model.

```typescript
import {grid, GridModel} from '@xh/hoist/cmp/grid';

const gridModel = new GridModel({
    store: {
        fields: ['name', 'value', 'date']
    },
    columns: [
        {field: 'name', flex: 1},
        {field: 'value', ...number},
        {field: 'date', ...date}
    ],
    sortBy: 'name'
});

// In component
grid({model: gridModel});
```

--------------------------------

### Custom PortfolioService example

Source: https://github.com/xh/hoist-react/blob/develop/svc/README.md

Example of creating a custom HoistService in TypeScript. Shows the class definition with observable state, an initAsync override, a method to load data via XH.fetchJson, and a getter. Also shows installation via XH.installServicesAsync and access via XH.portfolioService.

```typescript
import {HoistService, XH} from '@xh/hoist/core';
import {observable} from '@xh/hoist/mobx';

export class PortfolioService extends HoistService {
    @observableRef accessor portfolios: Portfolio[] = [];

    // Called during app startup
    override async initAsync() {
        await this.loadPortfoliosAsync();
    }

    async loadPortfoliosAsync() {
        const data = await XH.fetchJson({url: 'api/portfolios'});
        runInAction(() => this.portfolios = data);
    }

    getPortfolio(id: string): Portfolio {
        return this.portfolios.find(p => p.id === id);
    }
}

// Install in AppModel.initAsync()
await XH.installServicesAsync([PortfolioService], ctx);

// Access anywhere
XH.portfolioService.getPortfolio('abc123');
```

--------------------------------

### Good changelog entry examples

Source: https://github.com/xh/hoist-react/blob/develop/docs/changelog-format.md

Examples of well-written changelog bullets using past tense and specific API names.

```markdown
* Enhanced `GridModel` column state management to support partial updates.
* Added support for `warning` and `info` severity in `Field.rules`.
* Fixed regression with `Store.revert()` on stores with summary records.
```

--------------------------------

### hoist-docs usage examples

Source: https://github.com/xh/hoist-react/blob/develop/mcp/README.md

Examples of using the hoist-docs CLI to search documentation, list documents, read specific documents, and access shortcuts. Run 'npx hoist-docs --help' for full usage.

```bash
# Search documentation - returns ranked sections with excerpts
npx hoist-docs search "grid sorting"
npx hoist-docs search "authentication" --category concept

# List all available documents
npx hoist-docs list
npx hoist-docs list --category package

# Read a specific document by ID - whole, one section, or its outline
npx hoist-docs read cmp/grid
npx hoist-docs read cmp/grid --outline
npx hoist-docs read persistence --section "Built-in Model Support > GridModel"
npx hoist-docs read lifecycle-app

# Shortcuts for common documents
npx hoist-docs conventions     # docs/coding-conventions.md
npx hoist-docs index           # docs/README.md documentation catalog
```

--------------------------------

### Bootstrap Setup: Install ag-Grid and Highcharts

Source: https://github.com/xh/hoist-react/blob/develop/kit/README.md

Call installAgGrid and installHighcharts early in Bootstrap.ts to set up the required libraries. The version string for ag-Grid must match Hoist's required range.

```typescript
import {installAgGrid} from '@xh/hoist/kit/ag-grid';
import {installHighcharts} from '@xh/hoist/kit/highcharts';
import {AgGridReact} from 'ag-grid-react';
import Highcharts from 'highcharts/highstock';

installAgGrid(AgGridReact, '34.2.1');
installHighcharts(Highcharts);
```

--------------------------------

### Install services in AppModel.initAsync

Source: https://github.com/xh/hoist-react/blob/develop/core/README.md

Install custom services during app initialization. Multiple calls allow ordered initialization; services installed later can depend on earlier ones.

```typescript
class AppModel extends HoistAppModel {
    override async initAsync(ctx: InitContext) {
        // Install custom services - multiple calls for ordered initialization
        await XH.installServicesAsync([TradeService, PortfolioService], ctx);
        await XH.installServicesAsync([ReportService], ctx);  // Depends on above
    }
}
```

--------------------------------

### Install fetch headers after OAuth client init

Source: https://github.com/xh/hoist-react/blob/develop/docs/authentication.md

Shows the incorrect and correct ways to initialize the OAuth client and install default headers on FetchService. Without headers, requests fail with 401; with headers, the token is sent.

```typescript
// ❌ Don't: OAuth client initialized, but no headers installed
await this.client.initAsync();
return this.getAuthStatusFromServerAsync();  // 401 — no token sent

// ✅ Do: install headers before resolving the user
await this.client.initAsync();
XH.fetchService.addDefaultHeaders(async () => ({
    Authorization: `Bearer ${(await this.client.getIdTokenAsync()).value}`
}));
return this.getAuthStatusFromServerAsync();
```

--------------------------------

### Configure Vitest with setupFiles for shared server state

Source: https://github.com/xh/hoist-react/blob/develop/docs/unit-testing.md

Add a setup file via the setupFiles option of configureVitest() to seed server state before each spec file. This runs after Hoist's own setup.

```typescript
// vitest.config.mts
export default defineConfig(
    configureVitest({appCode: 'myApp', setupFiles: ['./src/test-support/setup.ts']})
);
```

--------------------------------

### Start Toolbox server with throwaway H2 database and temporary admin

Source: https://github.com/xh/hoist-react/blob/develop/CLAUDE.md

Use this command to start the Toolbox Grails server on a throwaway in-memory H2 database with a temporary admin user for agent-driven sessions. Always use exactly agent@xh.io / localDevOnly as credentials. The database starts empty and is discarded on stop, so features depending on stored data may not work.

```bash
cd ../toolbox
APP_TOOLBOX_USE_H2=true APP_TOOLBOX_OAUTH_PROVIDER=NONE \
APP_TOOLBOX_BOOTSTRAP_ADMIN_USER=agent@xh.io \
APP_TOOLBOX_BOOTSTRAP_ADMIN_PASSWORD=localDevOnly ./gradlew bootRun
```

--------------------------------

### Server-dependent test example for PrefService

Source: https://github.com/xh/hoist-react/blob/develop/docs/unit-testing.md

Complete example of a test file that boots the test app once per file, adjusts hoistCore state, and uses the fake server to verify behavior. Shows how to use hoistCore.requestsTo, server.use, and hoistError.

```typescript
import {XH} from '@xh/hoist/core';
import {hoistCore, hoistError, initTestAppAsync, server, xhUrl} from '@xh/hoist/test-support';
import {http} from 'msw';
import {beforeAll, describe, expect, it} from 'vitest';

describe('PrefService', () => {
    beforeAll(async () => {
        hoistCore.prefs.pageSize = {type: 'int', defaultValue: 50, value: 100};
        await initTestAppAsync();
    });

    it('sends changed prefs to the server as JSON', async () => {
        XH.setPref('pageSize', 200);
        await XH.prefService.pushPendingAsync();

        const [req] = hoistCore.requestsTo('xh/setPrefs');
        expect(req.json).toMatchObject({pageSize: 200});
        expect(req.query.clientUsername).toBe('jdoe');
    });

    it('rejects when the server reports a session mismatch', async () => {
        server.use(
            http.post(xhUrl('xh/setPrefs'), () =>
                hoistError(400, {name: 'SessionMismatchException', isRoutine: true})
            )
        );
        // ...
    });
});
```

--------------------------------

### fmtCompactDate and compactDateRenderer usage examples

Source: https://github.com/xh/hoist-react/blob/develop/format/README.md

Demonstrates fmtCompactDate and compactDateRenderer usage. Shows adaptive formatting based on distance from today, with examples for same-day, near, and distant dates. Also shows customizing the distantThreshold option.

```typescript
import {fmtCompactDate, compactDateRenderer} from '@xh/hoist/format';

// Assuming today is 2026-02-08:
fmtCompactDate(new Date('2026-02-08T15:45:00'))  // "3:45pm"    (same day → time only)
fmtCompactDate(new Date('2026-01-15T10:00:00'))  // "Jan 15"    (last month → month + day)
fmtCompactDate(new Date('2025-03-22T10:00:00'))  // "2025-03-22" (11 months ago → full date)

// LocalDate same-day defaults to 'MMM D' since there is no time component
fmtCompactDate(LocalDate.today())                // "Feb 8"

// Use as a column renderer for activity/event timestamps
{field: 'lastActivity', renderer: compactDateRenderer()}

// Custom thresholds — e.g. show full date after only 2 months
{field: 'updatedDate', renderer: compactDateRenderer({distantThreshold: 2})}
```

--------------------------------

### AppModel with Phased Service Installation

Source: https://github.com/xh/hoist-react/blob/develop/docs/lifecycle-models-and-services.md

Shows an AppModel that installs services in phases: first reference data services, then domain services concurrently, then sets up UI. Also overrides doLoadAsync to explicitly load services, passing loadSpec for staleness and auto-refresh awareness.

```typescript
class AppModel extends HoistAppModel {
    @managed tabModel: TabContainerModel;

    override async initAsync(ctx: InitContext) {
        // Phase 1: reference data (other services depend on these lookups)
        await XH.installServicesAsync([LookupService], ctx);

        // Phase 2: domain services (can initialize concurrently)
        await XH.installServicesAsync([OrderService, TradeService], ctx);

        // Phase 3: set up application UI
        this.tabModel = new TabContainerModel({
            route: 'default',
            track: true,
            tabs: [...]
        });
    }

    override async doLoadAsync(loadSpec: LoadSpec) {
        // Services must be explicitly loaded here — they are not in the
        // RefreshContextModel and will not load on app refresh otherwise.
        // Pass loadSpec through for staleness tracking and auto-refresh awareness.
        await XH.lookupService.loadAsync(loadSpec);
        await Promise.all([
            XH.orderService.loadAsync(loadSpec),
            XH.tradeService.loadAsync(loadSpec)
        ]);
    }
}
```

--------------------------------

### Managed Reaction and Autorun Examples

Source: https://github.com/xh/hoist-react/blob/develop/core/README.md

Examples of using addReaction and addAutorun for MobX subscription management. The first shows a single reaction with debounce, the second shows multiple specs, and the third shows an autorun. All are automatically disposed on destroy.

```typescript
// Managed reaction - explicitly declare what to track
this.addReaction({
    track: () => this.selectedId,
    run: id => this.loadDetailsAsync(id),
    debounce: 300  // optional debouncing
});
```

```typescript
// Preferred: pass multiple specs to a single addReaction call
this.addReaction(
    {track: () => this.selectedId, run: () => this.loadDetailsAsync()},
    {track: () => this.filters, run: () => this.applyFilters(), debounce: 100},
    {when: () => this.isReady, run: () => this.onReady()}  // one-time "when" form
);
```

```typescript
// Managed autorun - tracks whatever observables are read
this.addAutorun(() => {
    console.log('Selection changed to:', this.selectedRecord?.name);
});
```

--------------------------------

### Initialize services in phases with XH.installServicesAsync()

Source: https://github.com/xh/hoist-react/blob/develop/docs/lifecycle-models-and-services.md

Shows how to initialize services in phases during app startup. Services in a single call run concurrently; use separate awaited calls to enforce ordering.

```typescript
// In AppModel.initAsync()
override async initAsync(ctx: InitContext) {
    // Phase 1: reference data (must complete first)
    await XH.installServicesAsync([LookupService], ctx);

    // Phase 2: these can initialize concurrently
    await XH.installServicesAsync([OrderService, TradeService], ctx);
}
```

--------------------------------

### mcpInstructions registry example

Source: https://github.com/xh/hoist-react/blob/develop/docs/companion-library-docs.md

Shows how to add agent guidance in a library registry file. The server adds it to instructions under the library's name. Keep guidance under 1,500 characters; the server truncates longer text and logs a warning. The tools trim lines and drop blank lines, and ignore non-string values.

```json
{
  "mcpInstructions": [
    "Use acmeGrid and AcmeGridModel instead of grid and GridModel in Acme apps.",
    "Fetch through AcmeFetchService, which adds the Acme auth headers. Do not call XH.fetchService directly.",
    "Read @acme/hoist-acme/docs/README.md before you build a new screen."
  ],
  "entries": []
}
```

--------------------------------

### GET /api/users/{id}

Source: https://github.com/xh/hoist-react/blob/develop/docs/authorization.md

Example endpoint documentation.

```APIDOC
## [GET] /api/users/{id}

### Description
Retrieves a user by their unique identifier.

### Method
GET

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **name** (string) - The name of the user.
- **email** (string) - The email address of the user.

#### Response Example
{
  "id": "123",
  "name": "John Doe",
  "email": "john.doe@example.com"
}
```

--------------------------------

### Typical Entry Point Calling XH.renderApp()

Source: https://github.com/xh/hoist-react/blob/develop/docs/lifecycle-app.md

Shows a typical entry point file that imports the Bootstrap, core Hoist classes, and application-specific components/models, then calls XH.renderApp() with an AppSpec config. The five required properties are componentClass, modelClass, containerClass, isMobileApp, and checkAccess; the rest are optional.

```typescript
import '../Bootstrap';

import {XH} from '@xh/hoist/core';
import {AppContainer} from '@xh/hoist/desktop/appcontainer';
import {AppComponent} from '../desktop/AppComponent';
import {AppModel} from '../desktop/AppModel';
import {AuthModel} from '../core/AuthModel';

XH.renderApp({
    clientAppCode: 'app',
    clientAppName: 'Toolbox',
    componentClass: AppComponent,
    modelClass: AppModel,
    containerClass: AppContainer,
    authModelClass: AuthModel,
    isMobileApp: false,
    enableLogout: true,
    checkAccess: () => true
});
```

--------------------------------

### useHotkeys hook example

Source: https://github.com/xh/hoist-react/blob/develop/desktop/README.md

Registers keyboard shortcuts. The example binds Ctrl+S to a save action.

```typescript
import {useHotkeys} from '@xh/hoist/desktop/hooks';

const MyComponent = hoistCmp({
    render() {
        const el = div('Press Ctrl+S');
        return useHotkeys(el, [
            {combo: 'ctrl+s', label: 'Save', onKeyDown: save}
        ]);
    }
});
```

--------------------------------

### Bad changelog entry examples

Source: https://github.com/xh/hoist-react/blob/develop/docs/changelog-format.md

Examples of poorly written changelog bullets with incorrect tense and phrasing.

```markdown
* New support for warning severity in rules    (use "Added", not "New support for")
* Fix to regression in Store.revert            (use "Fixed regression", not "Fix to")
* Allow improved editing of columns            (use "Enhanced" or "Added", not "Allow")
```

--------------------------------

### Building a Desktop Panel example

Source: https://github.com/xh/hoist-react/blob/develop/desktop/README.md

Shows a typical desktop panel with a toolbar containing add, edit, and delete buttons, a grid, and a loading mask. The delete button is conditionally omitted based on user role.

```typescript
import {panel} from '@xh/hoist/desktop/cmp/panel';
import {toolbar, toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
import {button} from '@xh/hoist/desktop/cmp/button';
import {grid} from '@xh/hoist/desktop/cmp/grid';

const userListPanel = hoistCmp.factory({
    model: uses(UserListModel),

    render({model}) {
        return panel({
            title: 'Users',
            icon: Icon.users(),
            tbar: toolbar(
                button({text: 'Add', icon: Icon.add(), onClick: () => model.addUser()}),
                button({text: 'Edit', icon: Icon.edit(), onClick: () => model.editUser()}),
                '-',
                button({
                    text: 'Delete',
                    icon: Icon.delete(),
                    intent: 'danger',
                    onClick: () => model.deleteUser(),
                    omit: !XH.getUser().hasRole('DELETE_USER')
                }),
                filler(),
                storeFilterField()
            ),
            item: grid(),
            mask: 'onLoad'
        });
    }
});
```

--------------------------------

### Install Highcharts with installHighcharts

Source: https://github.com/xh/hoist-react/blob/develop/kit/README.md

Install Highcharts by calling installHighcharts() with the Highcharts instance. Requires Highcharts 12.4.0 – 12.*.*. On installation, Kit applies default options: comma thousands separator and numeric symbols k, m, b, t.

```typescript
// In Bootstrap.ts
import {installHighcharts} from '@xh/hoist/kit/highcharts';
import Highcharts from 'highcharts/highstock';

installHighcharts(Highcharts);
```

--------------------------------

### Field Configuration Example

Source: https://github.com/xh/hoist-react/blob/develop/data/README.md

Shows how to configure fields in a Store using the simple string form and full configuration objects. Includes options like type, displayName, description, defaultValue, rules, isDimension, and enableXssProtection. Note that XSS protection is disabled by default and can be enabled per field or app-wide via AppSpec.enableXssProtection.

```typescript
const store = new Store({
    fields: [
        // Simple string form
        'lastName',

        // Full configuration
        {
            name: 'salary',
            type: 'number',
            displayName: 'Annual Salary',
            description: 'Total annual compensation before taxes',
            defaultValue: 0,
            rules: [required, numberIs({min: 0})]
        },

        {name: 'department', type: 'string', isDimension: true},
        {name: 'hireDate', type: 'localDate'},

        // Opt in to DOMPurify escaping of incoming string values
        {name: 'comment', type: 'string', enableXssProtection: true}
    ]
});
```

--------------------------------

### domAttrs usage example

Source: https://github.com/xh/hoist-react/blob/develop/core/README.md

Example showing how to pass extra DOM attributes to a text input component using the domAttrs prop.

```APIDOC
## domAttrs

### Description
Pass extra DOM attributes to the primary DOM element of a Hoist component. Keys are constrained to `data-*` and `aria-*` attributes plus `role`.

### Usage

```typescript
textInput({
    bind: 'email',
    testId: 'signup-email',
    domAttrs: {'data-analytics-id': 'signup-email', 'aria-describedby': 'email-help'}
});
```

### Supported Components
- `Box` and layout components built on it (e.g., `Panel`, `Toolbar`)
- `Button` and `ButtonGroup`
- `Card` and `Badge`
- Input components in `/cmp/input/`

### Notes
- Inline `domAttrs` literals create a new object on each render; hoist a constant out of the render function when passing to a memoized component.
- Pre-built `Record<string, string>` can assign attributes outside the constrained set, but precedence against component-managed attributes is not guaranteed.
```

--------------------------------

### Button examples with primary and minimal variants

Source: https://github.com/xh/hoist-react/blob/develop/desktop/README.md

Shows two button examples: a primary button with check icon and a minimal refresh button with onClick handler.

```typescript
import {button} from '@xh/hoist/desktop/cmp/button';

button({text: 'Save', icon: Icon.check(), intent: 'primary'})
button({icon: Icon.refresh(), minimal: true, onClick: refresh})
```

--------------------------------

### ClientHealthService: Get health snapshot and register custom source

Source: https://github.com/xh/hoist-react/blob/develop/svc/README.md

Shows how to get the current health report and register a custom data source for health reports.

```typescript
// Get current health snapshot
const report = XH.clientHealthService.getReport();
// {general: {...}, memory: {...}, connection: {...}, webSockets: {...}}

// Register custom data source for health reports
XH.clientHealthService.addSource('myFeature', () => ({
    activeCount: myModel.activeItems.length,
    cacheSize: myModel.cache.size
}));
```

--------------------------------

### EnvironmentService: Get environment info and version

Source: https://github.com/xh/hoist-react/blob/develop/svc/README.md

Shows how to get environment metadata using the XH.getEnv() alias and access helper methods and observable properties directly from the service.

```typescript
// Environment info - use XH.getEnv() alias
XH.getEnv('appEnvironment');  // 'Production' | 'Development' | 'Staging' | etc.

// Helper methods and observable properties - access service directly
XH.environmentService.isProduction();
XH.environmentService.isTest();
XH.environmentService.serverVersion;  // Polled - can change without app refresh
XH.environmentService.serverBuild;
```

--------------------------------

### Example output of hoist-get-symbol for ColumnSpec

Source: https://github.com/xh/hoist-react/blob/develop/mcp/README.md

Abbreviated example output showing the format for an interface symbol, including import line, package, file, signature, documentation, and member summary.

```plaintext
# ColumnSpec (interface)
Import: import {ColumnSpec} from '@xh/hoist/cmp/grid';
Package: cmp/grid/columns
File: cmp/grid/columns/Column.ts
Exported: yes

## Signature
export interface ColumnSpec

## Documentation
Configuration object for defining a {@link Column} within a {@link GridModel}.
...

## Members (64 own, 0 inherited)
- field?: string | FieldSpec | CubeFieldSpec
- colId?: string
- isTreeColumn?: boolean
...
(4 more members not shown)

Full member details: hoist-ts members ColumnSpec [--filter <text>] [--include own|inherited] [--kind property|method|accessor].
```

--------------------------------

### Creating a Store with fields and initial data

Source: https://github.com/xh/hoist-react/blob/develop/data/README.md

Example of instantiating a Store with a field schema and initial data. Each record should have an 'id' property by default.

```typescript
import {Store} from '@xh/hoist/data';

const store = new Store({
    fields: [
        {name: 'name', type: 'string', displayName: 'Full Name'},
        {name: 'salary', type: 'number', defaultValue: 0},
        {name: 'department', type: 'string'},
        {name: 'hireDate', type: 'localDate'}
    ],
    data: initialData  // Each record should have an 'id' property (default idSpec)
});
```

--------------------------------

### Basic usage of TabContainerModel and tabContainer

Source: https://github.com/xh/hoist-react/blob/develop/cmp/tab/README.md

TypeScript example showing how to create a TabContainerModel with three tabs and render it using the tabContainer component. The example imports from '@xh/hoist/cmp/tab' and the desktop or mobile package.

```typescript
import {TabContainerModel} from '@xh/hoist/cmp/tab';
import {tabContainer} from '@xh/hoist/desktop/cmp/tab';  // or mobile

const tabModel = new TabContainerModel({
    tabs: [
        {id: 'overview', title: 'Overview', content: () => overviewPanel()},
        {id: 'details', title: 'Details', content: () => detailsPanel()},
        {id: 'history', title: 'History', content: () => historyPanel()}
    ],
    defaultTabId: 'overview'
});

// Render
tabContainer({model: tabModel})
```

--------------------------------

### Working with Subforms

Source: https://github.com/xh/hoist-react/blob/develop/cmp/form/README.md

Shows how to get a SubformsFieldModel and perform operations: add items (with or without index), remove items by passing the FormModel, access the subform array, and get flattened data.

```typescript
const lineItemsField = orderFormModel.getField('lineItems') as SubformsFieldModel;

// Add a new item
lineItemsField.add({
    initialValues: {product: '', quantity: 1, price: 0}
});

// Add at specific index
lineItemsField.add({index: 0, initialValues: {...}});

// Remove an item (pass the FormModel instance)
lineItemsField.remove(lineItemFormModel);

// Access subform array
const subforms = lineItemsField.value;  // FormModel[]

// Get all data (flattened)
const lineItemsData = lineItemsField.getData();  // PlainObject[]
```

--------------------------------

### Authentication Flow Phases

Source: https://github.com/xh/hoist-react/blob/develop/docs/authentication.md

Shows the sequence of app initialization phases during authentication, from PRE_AUTH through RUNNING.

```text
PRE_AUTH → AUTHENTICATING → INITIALIZING_HOIST → INITIALIZING_APP → RUNNING
```

--------------------------------

### Enable IntelliJ MCP server in local settings

Source: https://github.com/xh/hoist-react/blob/develop/CLAUDE.md

Adds the 'idea' server to the enabledMcpjsonServers array in .claude/settings.local.json. Requires a running IDE instance with the MCP server enabled. A read-only subset of tools is pre-approved; write/execute tools still prompt. IntelliJ rewrites its own entry on startup, so take its changes.

```json
{
  "enabledMcpjsonServers": ["hoist-react", "idea"]
}
```

--------------------------------

### fmtPercent examples

Source: https://github.com/xh/hoist-react/blob/develop/format/README.md

Shows `fmtPercent` multiplying by 100 and appending `%`. Pass the raw decimal ratio, not a pre-multiplied value. The third example uses `colorSpec` and `withSignGlyph` to render a red down arrow for negative values.

```typescript
fmtPercent(0.456)                            // "45.60%"
fmtPercent(0.456, {precision: 0})            // "46%"
fmtPercent(-0.032, {
    precision: 1,
    colorSpec: true,
    withSignGlyph: true
})                                            // "▾3.2%" (in red)
```

--------------------------------

### Build and publish Tomcat Docker image

Source: https://github.com/xh/hoist-react/blob/develop/docs/build-and-deploy-app.md

Build and publish the Tomcat Docker image. Must run with docker/tomcat as the working directory. Copies the WAR into the Docker context, builds with a tag including appCode and '-tomcat', pushes if successful, and returns the exit code to CI.

```bash
# Copy the WAR built above into the Docker context.
cp ../../build/libs/*.war .

# Determine an appropriate container tag.
containerTag=$DOCKER_REGISTRY/$APP_CODE-tomcat:$APP_VERSION
echo "Building Docker container $containerTag"
docker build --pull -t "$containerTag" .

# Note whether build was successful, push if so, return error if not.
ret=$?
if [ $ret -eq 0 ]
then
  docker push "$containerTag"
  ret=$?
else
  echo "Docker container build failed and was not pushed"
fi

# Cleanup and relay exit code to CI
rm *.war
exit $ret
```

--------------------------------

### Minimal registry JSON example

Source: https://github.com/xh/hoist-react/blob/develop/docs/companion-library-docs.md

Shows a minimal registry with two entries. Only entries[].id is required; title, description, keywords, and mcpCategory are optional.

```json
{
  "entries": [
    {"id": "docs/README.md", "title": "Acme Index", "mcpCategory": "index"},
    {
      "id": "grid/README.md",
      "title": "Acme Grids",
      "description": "AcmeGrid, the firm-standard wrapper around Hoist's grid.",
      "keywords": ["AcmeGrid", "AcmeGridModel", "GridModel", "export", "column presets"]
    }
  ]
}
```
Tokens:
Raw