Skip to content

README.md

Latest commit

 

History

History
114 lines (83 loc) · 6.16 KB

README.md

File metadata and controls

114 lines (83 loc) · 6.16 KB
Raw

JST — architecture-first React starter

CI status OpenSSF Scorecard Node.js 24 LTS React 19 MIT license

JST

An architecture-first React starter for products that need server rendering, explicit dependency boundaries, typed data flow, and enforceable quality gates from the first commit.

Documentation · Project health · Discussions

Quick start

Create a project with the official initializer:

npm create jst@latest my-app
# or, with pnpm
pnpm create jst@latest my-app

cd my-app
npm run dev

The initializer configures the project, installs dependencies, and starts from the clean application shell. Its completion screen shows the first slice, fast validation, and full release commands so the generated project is usable without returning to this README.

JST requires Node.js 24 LTS and supports npm and pnpm. Released CLI, template, and architecture-plugin combinations are recorded in jst.compatibility.json; project migrations use the same manifest instead of guessing from dependency versions.

Reproduce JST's central architecture claim locally:

npm run proof:architecture

The five-minute proof generates clean slices, introduces two real violations, verifies actionable failures, repairs them, and returns to green.

Showcase

The full architecture walkthrough and working API/persistence flows live in the independent JST Showcase, pinned here as the showcase Git submodule. Generated applications do not include it.

Create the reference application deliberately with npm create jst@latest my-demo -- --example showcase, or with pnpm: pnpm create jst@latest my-demo -- --example showcase.

Included

  • React 19 and React Router framework-mode SSR
  • TypeScript, Vite, and filesystem route discovery
  • Dependency injection with request-scoped composition and auto-discovered providers
  • A documented path for repository, DTO validation, mapper, service, view-model, entry, and props-driven view boundaries
  • CSS Modules, Stylelint, SVG sprites, Vitest, Playwright, Axe, ESLint boundaries, React Doctor, Knip, Husky, and lint-staged

Architecture

app → pages → modules → widgets → features → entities → shared

Dependencies point toward stable policy. Pages compose the application, features own user outcomes, entities own domain behavior and I/O contracts, and shared contains product-agnostic infrastructure only.

Read Architecture before adding a non-trivial vertical slice. Coding agents should follow the repository architecture skill.

Generated projects include @jst-stack/mcp. Connect your coding agent to npm run jst:mcp; it returns task-sized architecture context, runs the project generator, and exposes bounded quality gates without copying project policy into the server.

New to JST? Build the first production feature, then read why and when to use JST.

Commands

Command Purpose
npm run dev Start the SSR development server
npm run build Type-check and create production client/server builds
npm run test:unit Run unit and integration tests once
npm run test:e2e Run browser contracts and accessibility checks
npm run lint Check code, styles, and architecture boundaries
npm run validate Run the fast local gate: lint, types, and unit tests
npm run doctor Diagnose React correctness and maintainability issues
npm run audit:production Reject high-severity runtime dependency advisories
npm run check Run the complete code and production-build gate
npm run check:release Add SSR, hydration, accessibility, and browser contracts
npm run create:slice -- entity account Create a canonical entity, feature, or widget slice
npm run create:slice -- feature checkout --stateful Create a reactive feature with Reatom wiring
npm run create:slice -- module projectManagement --stateful Create a bounded-context mini-application
npm run create:package -- orderOperations Extract a reviewed workspace boundary with an ADR
npm run jst:mcp Start the project-local JST MCP server for coding agents
npm run proof:architecture Reproduce the architecture violation and repair loop
npm run template:setup Configure the new product

Project policy

Questions and proposals belong in JST Discussions. Maintained by @antonbelous0v and sustained through GitHub Sponsors.

Contributors

Thanks to everyone who improves JST through code, documentation, testing, and issue reports.