Installation

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

The prompts ask for a project name when you leave it out of the command, whether to start from the starter template or a GitHub repository, a package manager, whether to initialise git, and whether to install dependencies now. Then:

cd my-app
bun run start

For all flags and options, see Project scaffolding in the CLI reference. To start from the agent harness rather than the starter template, follow An agent of your own.

Manual installation

Add Routecraft and its CLI to an existing project:

bun add @routecraft/routecraft @routecraft/cli

Create your first capability:

// capabilities/my-first-capability/route.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-first-capability/route.ts

The CLI runs on Bun and loads .ts files natively, so no tsc step is required. craft start boots every capability under capabilities/ at once; see Project structure.

TypeScript configuration

A new project ships this tsconfig.json; use the same one for a manual installation:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Preserve",
    "moduleResolution": "bundler",
    "rootDir": ".",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "allowJs": true,
    "strict": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "resolveJsonModule": true
  },
  "include": ["**/*.ts", "**/*.js"],
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/*.config.ts",
    "vitest.config.ts",
    "craft.config.ts"
  ]
}

moduleResolution: "bundler" is what lets the extensionless relative imports used throughout these docs ('../send-email/route') resolve. TypeScript only typechecks (tsc --noEmit); nothing is compiled, because Bun runs the .ts files directly in development and in production.

Running in production

In production, run bun run start on a host with Bun, or build the scaffolded Dockerfile; see Deployment. To run capabilities inside an existing Node or Bun application instead of through the CLI, embed the library with ContextBuilder; see Programmatic invocation.

Where to go next