Cookbook Router
@cookbook/router-cli

CLI contract types

Public CLI data contracts for filesystems, route inputs, config loading, command results, manifests, watch handles, and build integration.

@cookbook/router-cli exposes one public package entrypoint.

This page documents the public CLI data contracts exported from that entrypoint.

It intentionally does not duplicate command behavior. Behavior belongs to the command, configuration, route-loading, generation, and build-integration pages.

Registration placeholders

interface Register {}

Register is reserved for future CLI-side module augmentation.

Current generated register.d.ts does not augment @cookbook/router-cli.

interface RouterContracts {}

RouterContracts is an empty placeholder shape re-exported by the CLI package.

It is not the generated application RouterContracts emitted in .cookbook-router/contracts.ts.

Configuration contracts

interface RouterCliConfig extends DefineRoutesOptions {
  readonly routeFiles?: string | readonly string[];
  readonly outDir?: string;
}

Prop

Type

RouterCliConfig extends DefineRoutesOptions, so it also accepts route-validation options such as pathOptions and pathConstraints.

interface RuntimeImportReference {
  readonly path: string;
  readonly exportName: string;
}

Prop

Type

interface GeneratedRouteTreeRuntimeOptions {
  readonly pathConstraints?: RuntimeImportReference;
}

Prop

Type

interface LoadedRouterConfig {
  readonly config: RouterCliConfig;
  readonly configFile: string;
  readonly rootDir: string;
  readonly runtimeRouteOptions?: GeneratedRouteTreeRuntimeOptions;
}

Prop

Type

type RouterConfigFilename =
  | 'cookbook-router.config.ts'
  | 'cookbook-router.config.mts'
  | 'cookbook-router.config.cts'
  | 'cookbook-router.config.js'
  | 'cookbook-router.config.mjs'
  | 'cookbook-router.config.cjs';

Filesystem contract

interface CliFileSystem {
  readFile(path: string): Promise<string>;

  writeFile(
    path: string,
    contents: string,
  ): Promise<void>;

  mkdir(
    path: string,
    options?: {
      readonly recursive?: boolean;
    },
  ): Promise<void>;

  readdir?(
    path: string,
    options?: {
      readonly withFileTypes?: false;
    },
  ): Promise<readonly string[]>;

  stat?(path: string): Promise<{
    readonly mtimeMs?: number;
    readonly isDirectory?: () => boolean;
    readonly isFile?: () => boolean;
  }>;

  watch?(
    path: string,
    listener: (
      event: 'rename' | 'change',
      filename: string | null,
    ) => void,
  ): {
    close: () => void;
  };
}

Prop

Type

Required capabilities depend on the operation.

OperationRequired filesystem methods
Explicit file loadingreadFile, writeFile, mkdir
Glob expansionreadFile, writeFile, mkdir, readdir, stat
Watch modereadFile, writeFile, mkdir, readdir, stat, watch

Route source contracts

interface RouteFileExport {
  readonly exportName: string;
  readonly kind: 'route' | 'routes' | 'routeTree';
}

Prop

Type

CliRouteSource is not re-exported from the package root index as a named public import.

It appears structurally in route-loading results:

interface CliRouteSource {
  readonly path: string;
  readonly routes: readonly RouteDefinition[];
  readonly routeOptions?: DefineRoutesOptions;
  readonly routeExports?: readonly RouteFileExport[];
}

Prop

Type

interface RouteFile {
  readonly routes: readonly RouteDefinition[];
  readonly routeOptions?: DefineRoutesOptions;
  readonly routeExports?: readonly RouteFileExport[];
  readonly routeSources?: readonly CliRouteSource[];
}

Prop

Type

interface LoadRouteFilesOptions {
  readonly routeFiles: readonly string[];
  readonly fs?: CliFileSystem;
}

Prop

Type

interface ResolvedRouteInput {
  readonly routeFile: RouteFile;
  readonly options: CliRouteOptions;
}

Prop

Type

Command option contracts

interface CliOutputOptions {
  readonly outDir?: string;
  readonly fs?: CliFileSystem;
}

Prop

Type

interface CliRouteOptions extends CliOutputOptions {
  readonly routes?: readonly RouteDefinition[];
  readonly routeFiles?: readonly string[];
  readonly routeFileWatchPaths?: readonly string[];
  readonly routeOptions?: DefineRoutesOptions;
  readonly configFile?: string;
  readonly cwd?: string;
  readonly verbose?: boolean;
  readonly allowEmptyRouteFiles?: boolean;
  readonly runtimeRouteOptions?: GeneratedRouteTreeRuntimeOptions;
}

Prop

Type

allowEmptyRouteFiles and runtimeRouteOptions are exported because shared engines carry them. They primarily support watchers and generated runtime imports.

Command-specific option contracts

interface InitOptions {
  readonly cwd?: string;
  readonly fs?: CliFileSystem;
  readonly routeFiles?: string | readonly string[];
  readonly outDir?: string;
  readonly configFile?: string;
  readonly starterRouteFile?: string;
  readonly skipGenerate?: boolean;
  readonly verbose?: boolean;
}
interface GenerateOptions extends CliRouteOptions {}

interface ManifestOptions extends CliRouteOptions {}

interface ValidateOptions extends CliRouteOptions {}

interface WatchCommandOptions extends WatchOptions {}
interface CliRunnerOptions {
  readonly stdout?: (message: string) => void;
  readonly stderr?: (message: string) => void;
  readonly version?: string;
}

Results and watch contracts

interface CommandResult {
  readonly ok: boolean;
  readonly files: readonly string[];
  readonly errors: readonly string[];
  readonly changedFiles?: readonly string[];
}

Prop

Type

interface WatchOptions extends CliRouteOptions {
  readonly debounceMs?: number;
  readonly onChange?: (
    result: CommandResult,
  ) => void | Promise<void>;
}

Prop

Type

interface WatchHandle {
  readonly initial: Promise<CommandResult>;
  close: () => void;
}

Prop

Type

Manifest contracts

interface ManifestRoute {
  readonly id: string;
  readonly path?: string;
  readonly parentId?: string;
  readonly index: boolean;
  readonly url?: RouterUrlOptions;
}

Prop

Type

interface RouteManifest {
  readonly routes: readonly ManifestRoute[];
}

Prop

Type

Build integration contracts

interface CookbookRouterBuilderPluginOptions {
  readonly cwd?: string;
  readonly configFile?: string;
  readonly routeFiles?: string | readonly string[];
  readonly outDir?: string;
  readonly fs?: CliFileSystem;
}

Prop

Type

interface RouterBuildRunnerOptions
  extends CookbookRouterBuilderPluginOptions {}
interface RouterBuildRunnerResult
  extends CommandResult {
  readonly watchPaths: readonly string[];
  readonly outDir: string;
  readonly error?: Error;
}

Prop

Type

interface RouterBuildRunner {
  run(): Promise<RouterBuildRunnerResult>;
}
interface RouterBuildWatchState {
  readonly watchPaths: readonly string[];
  readonly outDir: string;
}
interface RouterCompilerBuildHooksOptions
  extends RouterBuildRunnerOptions {
  readonly pluginName?: string;
}

Prop

Type

Export inventory

@cookbook/router-cli exports these registration placeholder types:

Register
RouterContracts

It exports these config and runtime-reference types:

GeneratedRouteTreeRuntimeOptions
LoadedRouterConfig
RouterCliConfig
RouterConfigFilename
RuntimeImportReference

It exports these filesystem and route-loading types:

CliFileSystem
LoadRouteFilesOptions
ResolvedRouteInput
RouteFile
RouteFileExport

It exports these command option and result types:

CliOutputOptions
CliRouteOptions
CliRunnerOptions
CommandResult
GenerateOptions
InitOptions
ManifestOptions
ValidateOptions
WatchCommandOptions
WatchHandle
WatchOptions

It exports these manifest types:

ManifestRoute
RouteManifest

It exports these build integration types:

CookbookRouterBuilderPluginOptions
RouterBuildRunner
RouterBuildRunnerOptions
RouterBuildRunnerResult
RouterBuildWatchState
RouterCompilerBuildHooksOptions

Not root public import targets

These source-level names are not exported from the package root as named public types:

CliRouteSource
CreateCliProgramOptions
CliProgramIo
ExpandRouteFilePatternsOptions
GenerateRouterArtifactsOptions
LoadRouterConfigOptions
ParseStaticRouteModuleOptions
RouteFilePatternWatchPathsOptions
RouterCompilationLike
RouterCompilerHook
RouterCompilerHooks
RouterCompilerLike
RouterCompilerLogger
RouterCompilerOptions
WatchIgnored
WatchIgnoredEntry

Some of these shapes appear in implementation signatures or nested exported types. That does not make them stable named imports from @cookbook/router-cli.

Where this bites

CLI RouterContracts is not generated application contracts

The CLI package exports this placeholder:

interface RouterContracts {}

The generated application file emits a concrete RouterContracts in .cookbook-router/contracts.ts.

Do not confuse the two.

CliRouteSource is structural here

RouteFile.routeSources exposes the shape, but the root package index does not export CliRouteSource as a named type.

Use RouteFile as the public result type, or annotate the local structural shape yourself.

CommandResult.changedFiles is optional

Not every command result includes changedFiles.

Consumers should treat it as optional.

Build runner error is not every failure

RouterBuildRunnerResult.error is only for thrown failures normalized by the runner.

Ordinary command failures return ok: false and errors, but may not include error.

Build integration API

Shared builder options, runner result, watch-state fallback, path utilities, error formatting, and Webpack/Rspack compiler hooks.

Error Reference

Exact Cookbook Router error messages, why they occur, and how to remove the cause rather than the evidence.

On this page

Registration placeholdersConfiguration contractsFilesystem contractRoute source contractsCommand option contractsCommand-specific option contractsResults and watch contractsManifest contractsBuild integration contractsExport inventoryNot root public import targetsWhere this bitesCLI RouterContracts is not generated application contractsCliRouteSource is structural hereCommandResult.changedFiles is optionalBuild runner error is not every failure