Webpack plugin

Install and configure

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

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

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

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

import CookbookRouterPlugin from '@cookbook/router-webpack-plugin';

export default {
  plugins: [new CookbookRouterPlugin()],
};

Named and default imports refer to the same class:

class CookbookRouterPlugin implements WebpackPluginInstance {
  constructor(options?: CookbookRouterPluginOptions);
  apply(compiler: Compiler): void;
}

interface CookbookRouterPluginOptions
  extends CookbookRouterBuilderPluginOptions {}

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.

Compiler lifecycle

The adapter delegates to applyRouterCompilerBuildHooks():

1. beforeRun generates and fails a normal build on error.
2. watchRun generates, reports errors, preserves previous valid files, and lets watch mode continue.
3. afterCompile adds current file, context, and missing dependencies.
4. The generated output directory is added to watchOptions.ignored without discarding existing ignore rules.

Missing dependencies matter. They allow Webpack to notice a config or route file that did not exist during the failed run.

Where this bites

Replacing compiler.options.watchOptions.ignored after plugin application can reintroduce output loops. Merge watch settings instead of overwriting them late.