Next.js Plugin

The @taserjs/router-plugin/next package integrates Taser.js into Next.js 15+ App Router compilation. It handles disk artifact generation in .taser/, TypeScript ambient type generation, and Turbopack/Webpack extension aliases.

Installation

Install @taserjs/router-plugin as a dev dependency:

pnpm add -D @taserjs/router-plugin

Basic Configuration

Wrap your next.config.ts using the createTaser (or withTaser) wrapper:

import type { NextConfig } from "next";
import { createTaser } from "@taserjs/router-plugin/next";

const nextConfig: NextConfig = {
  reactStrictMode: true,
};

const withTaser = createTaser({
  serverDir: "src/server", // Directory hosting Taser.js server code & routes
  entry: "@/server/taser", // Path alias or path to your router instance
  basePath: "/api", // URL prefix where Taser.js routes dispatch
});

export default withTaser(nextConfig);

You can also pass a function-based Next.js configuration:

import { withTaser } from "@taserjs/router-plugin/next";

export default withTaser({
  serverDir: "src/server",
  entry: "@/server/taser",
  basePath: "/api",
})((phase, { defaultConfig }) => {
  return {
    ...defaultConfig,
    reactStrictMode: true,
  };
});

Plugin Options

createTaser accepts configuration options conforming to TaserNextOptions:

const withTaser = createTaser({
  serverDir: "src/server",
  entry: "@/server/taser",
  basePath: "/api",
  outDir: ".taser",
});

How It Works Under the Hood

Next.js does not support serving virtual modules dynamically in runtime handlers. To provide zero-overhead integration, @taserjs/router-plugin/next:

1. Monitors src/server/routes/: In development (next dev), the plugin runs a lightweight background file watcher that synchronizes route changes instantly.
2. Generates Disk Artifacts in .taser/:
   • .taser/manifest.ts: Static route radix manifest tree.
   • .taser/entry.ts: Compiled router entry module exporting app, imported by your catch-all handler (src/app/api/[[...slug]]/route.ts).
   • .taser/app.ts: Composed router app module.
   • .taser/types/: Ambient TypeScript definitions (routes.d.ts, virtual.d.ts) for end-to-end type safety.
3. Configures Turbopack and Webpack:
   • Injects extension aliases so TypeScript module resolution and path aliases resolve across .ts, .tsx, and .js seamlessly.

Next Steps