System requirements, manual setup, and production builds.

System requirements

• Bun 1.1.0 or later - required to run the craft CLI. Bun has native TypeScript support so .ts capabilities run directly with no build step.
• Node.js 22.6 or later - only needed if you embed @routecraft/routecraft inside a Node application instead of using the CLI. Node 23.6+ recommended (type stripping is on by default).
• macOS, Windows (including WSL), or Linux.

The CLI is Bun-only. See the Runtime reference for the rationale and the Node embedding path.

Create a new project

Scaffold a complete Routecraft project with one command:

bunx create-routecraft my-app

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

cd my-app
bun run start

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

Manual installation

Add Routecraft to an existing project:

bun add @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 (requires Bun on the machine):

bunx craft run capabilities/my-capability.ts

The CLI runs on Bun and loads .ts files natively, so no tsc step is required.

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:

bun run build && bun 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

To run capabilities from inside an existing Node or Bun application, use ContextBuilder directly instead of the CLI. This is the recommended path for Node users.

import { ContextBuilder, craft, direct, log } from "@routecraft/routecraft";

const route = craft()
  .id("greet")
  .from(direct<{ name: string }>())
  .transform((body) => `Hello, ${body.name}!`)
  .to(log());

const { context, client } = await new ContextBuilder().routes(route).build();
context.start();

await client.send("greet", { name: "World" });

You get full programmatic control: load specific capability files, run a single capability for a batch job, or integrate Routecraft into a larger Express, Next.js, or Fastify server. See the Programmatic Invocation guide for the full pattern.

Related