Shared plugin options

Shared build-runner options

All plugins except Vite extend CookbookRouterBuilderPluginOptions from @cookbook/router-cli.

The runner resolves command options, generates physical artifacts, and then resolves watch paths even after a failure. That last part is the recovery mechanism: a bad config should not make the plugin blind to the file that can repair it.

Generated artifacts

A successful aggregate run writes:

• contracts.ts
• register.d.ts
• manifest.json

It writes routes.ts only when the loaded route input contains statically composable route exports. JSON-only or otherwise non-composable input can still produce contracts and a manifest without producing a runtime route module.

Precedence

1. Explicit plugin options
2. Values from cookbook-router.config.*
3. Framework defaults

An explicit routeFiles or outDir is not merged with the config value. It replaces it.

Runner result

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

createRouterBuildRunner() normalizes thrown failures into this result. Plugins do not need to guess where to keep watching after generation breaks.

Filesystem adapters

fs must satisfy the exported CliFileSystem. Generation requires readFile, writeFile, and mkdir. Glob discovery additionally needs readdir and stat. Watch mode additionally needs watch.

Where this bites

A custom filesystem with no readdir and stat can load explicit files, but it cannot expand route globs. The CLI reports that boundary instead of pretending a glob is a filename.