@zomme/bun-plugin-tsr

Bun plugin for TanStack Router route generation with file-based routing.

Features

- Automatic route tree generation from file structure
- Watch mode for development (auto-regenerates on file changes)
- Configurable via bunfig.toml
- Supports multiple root directories
- Full TypeScript support

Installation

``bash
bun add -d @zomme/bun-plugin-tsr
`

Install peer dependencies:

`bash
bun add @tanstack/react-router
bun add -d @tanstack/router-generator
`

Usage

$3

Add the plugin to your bunfig.toml:

`toml
[serve.static]
plugins = ["@zomme/bun-plugin-tsr"]
`

Or use it programmatically:

`typescript
import tsr from "@zomme/bun-plugin-tsr";

Bun.build({
entrypoints: ["./src/index.tsx"],
plugins: [tsr],
});
`

$3

Configure via bunfig.toml:

`toml
[plugins.tsr]
rootDirectory = "src"
routesDirectory = "./routes"
generatedRouteTree = "routeTree.gen.ts"
quoteStyle = "double"
routeFileIgnorePattern = ".test."
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| rootDirectory | string \| string[] | "src" | Root directory for routes |
| routesDirectory | string | "./routes" | Routes directory relative to root |
| generatedRouteTree | string | "routeTree.gen.ts" | Output file name |
| quoteStyle | "single" \| "double" | "double" | Quote style in generated code |
| routeFileIgnorePattern | string | ".test." | Pattern to ignore route files |

Directory Structure

Create routes using file-based routing:

`
src/
├── routes/
│ ├── __root.tsx # Root layout
│ ├── index.tsx # / (home page)
│ ├── about.tsx # /about
│ ├── dashboard/
│ │ ├── index.tsx # /dashboard
│ │ ├── settings.tsx # /dashboard/settings
│ │ └── $userId.tsx # /dashboard/:userId (dynamic)
│ └── posts/
│ ├── index.tsx # /posts
│ └── $postId.tsx # /posts/:postId (dynamic)
├── routeTree.gen.ts # Generated route tree (auto)
└── main.tsx
`

$3

| File Name | Route Path | Description |
|-----------|------------|-------------|
| index.tsx | / | Index route |
| about.tsx | /about | Static route |
| $userId.tsx | /:userId | Dynamic parameter |
| posts.$postId.tsx | /posts/:postId | Nested dynamic |
| __root.tsx | - | Root layout |
| -components/ | - | Private folder (ignored) |

Example

$3

`tsx
// src/routes/__root.tsx
import { Outlet, createRootRoute } from "@tanstack/react-router";

export const Route = createRootRoute({
component: RootComponent,
});

function RootComponent() {
return (



);
}
`

$3

`tsx
// src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
component: HomePage,
});

function HomePage() {
return

Welcome Home

;
}
`

$3

`tsx
// src/routes/posts/$postId.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/posts/$postId")({
component: PostPage,
loader: async ({ params }) => {
const post = await fetchPost(params.postId);
return { post };
},
});

function PostPage() {
const { post } = Route.useLoaderData();
return

{post.title}

;
}
`

$3

`tsx
// src/main.tsx
import { RouterProvider, createRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

const router = createRouter({ routeTree });

declare module "@tanstack/react-router" {
interface Register {
router: typeof router;
}
}

function App() {
return ;
}
`

Watch Mode

In development (NODE_ENV !== "production"), the plugin automatically watches for file changes:

- Create: New route files are detected and added
- Update: Modified routes trigger regeneration
- Delete: Removed files are cleaned from route tree

`bash


Development - watch mode enabled

bun dev

Production - no watch mode

NODE_ENV=production bun build
`

Multiple Root Directories

Support multiple entry points:

`toml
[plugins.tsr]
rootDirectory = ["apps/web/src", "apps/admin/src"]
`

Generated Route Tree

The plugin generates a routeTree.gen.ts file:

`typescript
// This file is auto-generated by @zomme/bun-plugin-tsr

import { Route as rootRoute } from "./routes/__root";
import { Route as IndexRoute } from "./routes/index";
import { Route as AboutRoute } from "./routes/about";
import { Route as DashboardIndexRoute } from "./routes/dashboard/index";

const routeTree = rootRoute.addChildren([
IndexRoute,
AboutRoute,
DashboardIndexRoute,
]);

export { routeTree };
`

How It Works

1. Scan: Plugin scans routesDirectory for route files
2. Parse: Analyzes file names for route patterns
3. Generate: Creates route tree with proper nesting
4. Watch: In dev mode, watches for changes and regenerates

Requirements

- Bun >= 1.0.0
- @tanstack/react-router >= 1.0.0
- @tanstack/router-generator` >= 1.0.0

License

MIT