Installation

Choose your runtime

For React applications

Install the core router and its React integration.

pnpm add @cookbook/router @cookbook/router-react

npm install @cookbook/router @cookbook/router-react

yarn add @cookbook/router @cookbook/router-react

bun add @cookbook/router @cookbook/router-react

Use this setup for React providers, links, hooks, outlets, slots, intercepts, blockers, and static rendering.

Other frameworks and runtimes

Install the core router.

pnpm add @cookbook/router

npm install @cookbook/router

yarn add @cookbook/router

bun add @cookbook/router

The core router is framework-agnostic and works independently of React or any other UI library.

Add generation to your build

Generation turns static route definitions into typed route IDs, params, search, hash, autocomplete, declarations, manifests, and build-time validation.

Install the CLI and exactly one plugin for the bundler your application uses.

No supported bundler plugin

Use the CLI directly when the application uses another build system or needs generation outside the bundler lifecycle.

pnpm add -D @cookbook/router-cli
pnpm exec cbr generate --watch

npm install --save-dev @cookbook/router-cli
npx cbr generate --watch

yarn add --dev @cookbook/router-cli
yarn cbr generate --watch

bun add --dev @cookbook/router-cli
bunx cbr generate --watch

Initialize Cookbook Router

Run the initializer once after installing the runtime and generation packages:

pnpm exec cbr init

npx cbr init

yarn cbr init

bunx cbr init

The initializer prepares the project for both CLI and bundler-plugin generation. It creates the router config, detects the source directory, adds route scripts, connects the generated output to TypeScript, and runs the first generation.

By default, it creates:

cookbook-router.config.ts
src/root.route.tsx
.cookbook-router/

Projects using an app directory get app/root.route.tsx instead. Custom route globs do not receive an automatic starter route.

cbr init refuses to overwrite an existing router config. Existing projects should configure generation manually instead of forcing initialization over working setup.

Verify the TypeScript connection

Generated contracts do nothing if TypeScript cannot see them. Whether the CLI or a bundler plugin creates the files, inference, autocomplete, and validation only work after those files become part of the application's TypeScript program.

cbr init updates tsconfig.json automatically when it finds one. Check the configuration manually when initialization was skipped, the bundler plugin was configured by hand, or generation uses a custom outDir.

Register the generated files to TypeScript's include option:

{
  "include": [
    "src",
    ".cookbook-router/contracts.ts",
    ".cookbook-router/register.d.ts"
  ]
}

Replace src when your source lives elsewhere. If you configured a different outDir, replace .cookbook-router with that path.

contracts.ts contains the route-specific types. register.d.ts connects these types to @cookbook/router and @cookbook/router-react, making route IDs, params, search, hash, metadata, and related specs available to links, navigation, hooks, and router APIs.

Do not add these files to compilerOptions.types. They must be included as source files in the TypeScript program.

No inclusion, no inference.