System requirements, manual setup, and production builds.

System requirements

• Node.js 22.6 or later - required for the --experimental-strip-types flag, which lets you run .ts files directly without a build step.
• Node.js 23.6 or later - recommended. TypeScript stripping is stable and enabled by default; no flags needed.
• macOS, Windows (including WSL), or Linux.

Create a new project

Scaffold a complete Routecraft project with one command:

npm create routecraft@latest my-app

Follow the prompts to configure your project name, package manager, and directory layout. Then:

cd my-app
npm run start

For all flags and options, see CLI -- create.

Manual installation

Add Routecraft to an existing project:

npm install @routecraft/routecraft

Create your first capability:

// capabilities/my-capability.ts
import { craft, simple, log } from "@routecraft/routecraft";

export default craft()
  .id("my-first-capability")
  .from(simple("Hello, Routecraft!"))
  .to(log());

Run it directly with the CLI:

npx @routecraft/cli run capabilities/my-capability.ts

On Node 22.6+, the CLI strips TypeScript at runtime with no tsc step required. On Node 23.6+ this happens automatically without any flags.

TypeScript configuration

Routecraft is TypeScript-first. The recommended tsconfig.json for a capabilities project:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist"
  },
  "include": ["capabilities/**/*.ts", "src/**/*.ts"]
}

You only need to compile (tsc) when building for production. During development, the CLI runs your .ts files directly.

Production builds

Build and start for production:

npm run build && npm run start

The build step compiles your capabilities to JavaScript. The compiled output in dist/ is what runs in production with no Node flags and no runtime overhead.

Embedding Routecraft in your app

If you're running capabilities from within an existing Node application instead of using the CLI, use CraftContext directly:

import { CraftContext } from "@routecraft/routecraft";

const ctx = new CraftContext();
await ctx.load("capabilities/");
await ctx.start();

This gives you full programmatic control: load specific capability files, run a single capability for a batch job, or integrate Routecraft into a larger Express or Fastify server.

Related