esbuild plugin

Install and configure

pnpm add -D @cookbook/router-esbuild-plugin

npm install --save-dev @cookbook/router-esbuild-plugin

yarn add -D @cookbook/router-esbuild-plugin

bun add -d @cookbook/router-esbuild-plugin

import { build } from 'esbuild';
import { cookbookRouterEsbuildPlugin } from '@cookbook/router-esbuild-plugin';

await build({
  entryPoints: ['src/main.tsx'],
  bundle: true,
  plugins: [cookbookRouterEsbuildPlugin()],
});

function cookbookRouterEsbuildPlugin(
  options?: CookbookRouterEsbuildPluginOptions,
): Plugin;

interface CookbookRouterEsbuildPluginOptions
  extends CookbookRouterBuilderPluginOptions {}

The factory is exported by name and as the default export.

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.

Lifecycle and errors

The plugin registers one onStart callback. Success returns no result. Failure returns:

{
  errors: [{ text: formatRouterBuildErrors(result.errors) }]
}

That lets esbuild render the generation failure in its normal error channel.

Watch boundary

The adapter does not register route-root watches. esbuild can rerun onStart when its own graph changes, but a brand-new matching route outside that graph is not guaranteed to trigger it. Run cbr generate --watch alongside esbuild watch mode when route creation/deletion must be discovered independently.