Type-safe, declarative building blocks for applications.
Declare. Yield. Derive. Compile — no surprises.

npm · Documentation · Issues · Discussions

craft-ts is a Signal-first toolkit for modeling state, asynchronous work, services, forms, dependency injection, and routes with explicit dependencies and strong TypeScript inference. RxJS remains optional. Angular is an optional island via @craft-ts/angular.

It is designed to keep application behavior close to where it is used while making dependency graphs visible to the compiler and to tests.

• One reactive model for every kind of state — state, query, mutation, asyncProcess, and queryParams cover local, server, asynchronous, and URL state.
• Composable behavior — insertions add reusable capabilities such as persistence, entity management, selection, pagination placeholders, and optimistic updates.
• Function-based services — craftService composes state and dependencies; toCraftService (from @craft-ts/angular) adapts existing Angular services and tokens.
• Type-safe routing and DI — typed dependency injection, navigation, route inputs, route providers, guards, pending UI, and lazy-load error handling.
• Derived forms — form state, validation, submission, and interdependent logic remain reactive and declarative.
• Deterministic testing — tests describe the real dependency graph and can isolate browser or platform boundaries explicitly.
• Observability by design — exceptions, correlations, and application state can be captured where failures occur.

@craft-ts/core and @craft-ts/component have no Angular peer dependencies. Angular remains optional through @craft-ts/angular when you need Angular islands. Node.js 20.19+ (or 22.12+) and TypeScript 5.9+ are required.

npm install @craft-ts/core@beta @craft-ts/component@beta
npm install @craft-ts/angular@beta # optional Angular islands
npm install -D @craft-ts/dev-tools@beta

The packages are currently published on the beta channel. @craft-ts/core provides the reactive primitives, @craft-ts/component provides selectorless functional components, @craft-ts/angular adapts Angular components and services, and @craft-ts/dev-tools provides the codemods and ESLint rules used by the type-safe DI and routing workflow.

Create granular state and derive its public API directly from it:

import{button,craftComponent,p}from'@craft-ts/component';import{craftComputed,state}from'@craft-ts/core';exportconstCounter=craftComponent('Counter',{},function*(){constcounter=yield*state('counter',0,({ state, update, set })=>({increment: ()=>update((value)=>value+1),reset: ()=>set(0),doubled: craftComputed(function*(){return(yield*state())*2;}),}));return{ counter };},({ counter })=>[p(function*(){return`Count: ${yield*counter()} (doubled: ${yield*counter.doubled()})`;}),button({click: counter.increment},'Increment'),],);

When logic must be shared, package the same primitives in a named service:

import{craftService,state}from'@craft-ts/core';const{ Counter }=craftService({name: 'Counter',scope: 'global'},function*(){constcounter=yield*state('counter',0,({ update })=>({increment: ()=>update((value)=>value+1),}));returncounter;},);const{ CounterConsumer }=craftService({name: 'CounterConsumer',scope: 'global'},function*(){constcounter=yield*Counter();returncounter;},);

Continue with the getting-started guide, then explore:

• Reactive primitives
• Services and dependency composition
• Forms
• Type-safe DI and routing
• Runnable examples
• Migration tooling

This repository is an npm workspace managed with Nx.

apps/
├── demo/ Angular application used for examples and integration checks
│ (`architecture/` — static graph Vitest suite)
└── docs/ VitePress documentation and documentation tests
libs/
├── core/ Published @craft-ts/core package
├── component/ Published @craft-ts/component package
├── dev-tools/ Published codemods and ESLint tooling
└── test-type/ Compile-time type test utilities
tools/
└── generators/ Nx generators and type-stress fixtures

• Node.js 20.19+ (or 22.12+)
• npm

Install the exact dependency versions from the lockfile:

npm ci

Start the Angular demo:

npx nx serve demo

La commande lance toutes les routes définies dans apps/demo/src/app/app.routes.ts. Le type-check de la démo est exécuté en parallèle du serveur Vite. Pendant son exécution, un indicateur discret Type checking in progress… apparaît en haut à droite de la page. Si le contrôle échoue, un grand overlay signale l’erreur mais le serveur reste accessible pour continuer l’investigation.

Start the documentation site at http://localhost:5173:

npx nx dev docs

1. Find the relevant implementation under libs/core/src/ or libs/dev-tools/src/.
2. Add or update focused tests next to the affected code.
3. Update the matching page under apps/docs/; the documentation is the reference for public behavior.
4. Add or update an example in apps/demo/ when the change benefits from an executable use case.
5. Run the focused Nx targets while iterating, then run the full validation suite before opening a pull request.

Useful focused commands:

npx nx test craft-ts-core
npx nx lint craft-ts-core
npx nx build craft-ts-core
npx nx test docs
npx nx build docs
npx nx architecture demo

npx nx architecture demo runs the Vitest suite in apps/demo/architecture/. See apps/demo/README.md for the commands and the rules it imports.

Inspect all targets available for a project with:

npx nx show project craft-ts-core

Run the same core checks as CI:

npx nx format:check
npx nx run-many -t lint test build typecheck e2e-ci

To automatically format changed files first:

npx nx format:write

Documentation pages live in apps/docs/ and the sidebar is configured in apps/docs/.vitepress/config.mts.

When documenting a public API:

• place the page in the matching domain folder (primitives, insertions, store, forms, utils, or type-safe-di-routes);
• show the relevant import statement;
• favor complete, compilable examples;
• add the page to the VitePress sidebar when necessary;
• run both npx nx test docs and npx nx build docs.

@craft-ts/core, @craft-ts/component, and @craft-ts/dev-tools are released together with one local command. It versions and builds the packages, publishes npm, deploys the built documentation, and synchronizes the complete demo used by StackBlitz:

npm run release:local -- patch
npm run release:local -- minor
npm run release:local -- major

An exact version, including a prerelease, is also accepted:

npm run release:local -- 0.6.0-beta.3

Beta releases use an explicit -beta.N version. Increment N for each beta; the command automatically publishes it under the npm beta dist-tag and marks the GitHub Release as a prerelease.

See RELEASING.md for the required sibling workspaces, safe preview, authentication, supported versions, and recovery guidance.

Bug reports, design discussions, documentation improvements, and pull requests are welcome. For substantial API changes, open a discussion or an issue first so the intended behavior can be agreed before implementation.

MIT © Romain Geffrault