Skip to content

getting-started.md

Latest commit

 

History

History
101 lines (67 loc) · 4.16 KB

getting-started.md

File metadata and controls

101 lines (67 loc) · 4.16 KB
Raw

Build the first production feature

This walkthrough takes a clean JST application from generation to a release-ready vertical slice. It deliberately triggers one architecture error so the repair path is clear.

1. Create and verify the application

npm create jst@latest order-board
# or, with pnpm
pnpm create jst@latest order-board

cd order-board
npm run validate

validate is the fast edit loop. check:release adds the production build, dependency audit, SSR, hydration, accessibility, and browser contracts.

If your coding agent supports MCP, configure a stdio server with npm run jst:mcp (pnpm run jst:mcp in a pnpm project). Start each implementation with jst_start_task. A local style or documentation edit receives a small task-specific contract; generator capabilities and full boundary guidance are returned only when the task introduces a new entity, feature, module, or widget.

2. Generate the boundaries

npm run create:slice -- entity order
npm run create:slice -- feature browseOrders --stateful

Run npm run create:slice -- --help for repository, service, persistence, UI, test, style, and non-interactive options. Extend the generated contracts and Reatom wiring instead of rebuilding their conventions from package internals.

The entity owns order vocabulary and external data. The feature owns the browsing workflow and interaction state. The page composes both. Do not start with JSX and invent ownership afterward.

3. Implement the data path

Use this order:

order DTO parser
  → order mapper/model
  → repository port and HTTP adapter
  → order service
  → browseOrders store
  → browseOrders entry
  → props-driven view

Keep each contract narrow:

  • order.dto.ts describes transport data and validates the untrusted response.
  • order.mapper.ts converts the DTO to the domain Order model.
  • order.repository.ts implements endpoint access; its port exposes only the operation the service needs.
  • order.service.ts owns the use case independently from React.
  • browseOrders.store.ts owns pending, error, empty, ready, and refresh interaction states.
  • browseOrders.entry.tsx observes the store and maps state to view props.
  • browseOrders.component.tsx renders props and emits callbacks.

Bind the repository/service through a discovered *.provider.ts composition module. Do not call useService below app or pages.

The complete working equivalent is the post entity and requestPosts feature in JST Showcase.

4. Compose the route

Import each slice through its <slice>.public.ts entry from the owning page. Keep route.tsx limited to route metadata and page composition.

If Knip reports the generated slice as unreachable, it has not been composed yet; do not suppress the report.

5. See a guardrail work

Temporarily call fetch from the feature view and run:

npm run lint

JST reports jst/effects-at-boundary. Remove the call and place transport access in the entity repository adapter. This is the normal repair model: move the decision or effect to its owner instead of disabling the rule.

Use Troubleshooting for import, naming, effect, UI, SSR, and generated-slice diagnostics.

6. Test the risky transitions

  • Unit-test DTO rejection and mapping.
  • Substitute the repository port in the service test.
  • Exercise loading, failure, empty, refresh, and stale-response behavior in the store test.
  • For mutations, test overlapping operations and an out-of-order failure; a late outcome must not overwrite newer state.
  • Cover the user-visible flow with role-based Playwright locators.

Tests use the same public APIs as production code. Do not deep-import another slice's private test utilities.

7. Run the release gate

First apply safe mechanical fixes:

npm run lint:fix

Then repair only the remaining responsibility, size, complexity, type, and behavior findings before running the full gate:

npm run check:release

The feature is complete only when source rules, architecture, types, tests, SSR build, production dependencies, hydration, accessibility, and browser behavior agree.