rsbuild-plugin-react-router
A Rsbuild plugin that provides seamless integration with React Router, supporting both client-side routing and server-side rendering (SSR).
Features
- π Zero-config setup with sensible defaults
- π Automatic route generation from file system
- π₯οΈ Server-Side Rendering (SSR) support
- π± Client-side navigation
- π οΈ TypeScript support out of the box
- π§ Customizable configuration
- π― Support for route-level code splitting
Installation
npm install rsbuild-plugin-react-router
yarn add rsbuild-plugin-react-router
pnpm add rsbuild-plugin-react-router
Usage
Add the plugin to your rsbuild.config.ts
:
import { defineConfig } from '@rsbuild/core';
import { pluginReactRouter } from 'rsbuild-plugin-react-router';
import { pluginReact } from '@rsbuild/plugin-react';
export default defineConfig(() => {
return {
plugins: [
pluginReactRouter({
customServer: false,
serverOutput: "commonjs",
federation: false
}),
pluginReact()
],
};
});
Configuration
The plugin uses a two-part configuration system:
- Plugin Options (in
rsbuild.config.ts
):
pluginReactRouter({
customServer?: boolean,
serverOutput?: "commonjs" | "module"
federation?: boolean
})
- React Router Configuration (in
react-router.config.ts
):
import type { Config } from '@react-router/dev/config';
export default {
ssr: true,
buildDirectory: 'dist',
appDirectory: 'app',
basename: '/my-app',
} satisfies Config;
All configuration options are optional and will use sensible defaults if not specified.
Default Configuration Values
If no configuration is provided, the following defaults will be used:
{
customServer: false
}
{
ssr: true,
buildDirectory: 'build',
appDirectory: 'app',
basename: '/'
}
Route Configuration
Routes can be defined in app/routes.ts
using the helper functions from @react-router/dev/routes
:
import {
type RouteConfig,
index,
layout,
prefix,
route,
} from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('about', 'routes/about.tsx'),
layout('routes/docs/layout.tsx', [
index('routes/docs/index.tsx'),
route('getting-started', 'routes/docs/getting-started.tsx'),
route('advanced', 'routes/docs/advanced.tsx'),
]),
...prefix('projects', [
index('routes/projects/index.tsx'),
layout('routes/projects/layout.tsx', [
route(':projectId', 'routes/projects/project.tsx'),
route(':projectId/edit', 'routes/projects/edit.tsx'),
]),
]),
] satisfies RouteConfig;
The plugin provides several helper functions for defining routes:
index()
- Creates an index route
route()
- Creates a regular route with a path
layout()
- Creates a layout route with nested children
prefix()
- Adds a URL prefix to a group of routes
Route Components
Route components support the following exports:
Client-side Exports
default
- The route component
ErrorBoundary
- Error boundary component
HydrateFallback
- Loading component during hydration
Layout
- Layout component
clientLoader
- Client-side data loading
clientAction
- Client-side form actions
handle
- Route handle
links
- Prefetch links
meta
- Route meta data
shouldRevalidate
- Revalidation control
Server-side Exports
loader
- Server-side data loading
action
- Server-side form actions
headers
- HTTP headers
Custom Server Setup
The plugin supports two ways to handle server-side rendering:
-
Default Server Setup: By default, the plugin automatically sets up the necessary middleware for SSR.
-
Custom Server Setup: For more control, you can disable the automatic middleware setup by enabling custom server mode:
import { defineConfig } from '@rsbuild/core';
import { pluginReactRouter } from 'rsbuild-plugin-react-router';
import { pluginReact } from '@rsbuild/plugin-react';
export default defineConfig(() => {
return {
plugins: [
pluginReactRouter({
customServer: true
}),
pluginReact()
],
};
});
When using a custom server, you'll need to:
- Create a server handler (
server/index.ts
):
import { createRequestHandler } from '@react-router/express';
export const app = createRequestHandler({
build: () => import('virtual/react-router/server-build'),
getLoadContext() {
return {
};
},
});
- Set up your server entry point (
server.js
):
import { createRsbuild, loadConfig } from '@rsbuild/core';
import express from 'express';
import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const app = express();
const isDev = process.env.NODE_ENV !== 'production';
async function startServer() {
if (isDev) {
const config = await loadConfig();
const rsbuild = await createRsbuild({
rsbuildConfig: config.content,
});
const devServer = await rsbuild.createDevServer();
app.use(devServer.middlewares);
app.use(async (req, res, next) => {
try {
const bundle = await devServer.environments.node.loadBundle('app');
await bundle.app(req, res, next);
} catch (e) {
next(e);
}
});
const port = Number.parseInt(process.env.PORT || '3000', 10);
const server = app.listen(port, () => {
console.log(`Development server is running on http://localhost:${port}`);
devServer.afterListen();
});
devServer.connectWebSocket({ server });
} else {
app.use(express.static(path.join(__dirname, 'build/client'), {
index: false
}));
const serverBundle = await import('./build/server/static/js/app.js');
app.use(async (req, res, next) => {
try {
await serverBundle.default.app(req, res, next);
} catch (e) {
next(e);
}
});
const port = Number.parseInt(process.env.PORT || '3000', 10);
app.listen(port, () => {
console.log(`Production server is running on http://localhost:${port}`);
});
}
}
startServer().catch(console.error);
- Update your
package.json
scripts:
{
"scripts": {
"dev": "node server.js",
"build": "rsbuild build",
"start": "NODE_ENV=production node server.js"
}
}
The custom server setup allows you to:
- Add custom middleware
- Handle API routes
- Integrate with databases
- Implement custom authentication
- Add server-side caching
- And more!
Cloudflare Workers Deployment
To deploy your React Router app to Cloudflare Workers:
- Configure Rsbuild (
rsbuild.config.ts
):
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginReactRouter } from 'rsbuild-plugin-react-router';
export default defineConfig({
environments: {
node: {
performance: {
chunkSplit: { strategy: 'all-in-one' },
},
tools: {
rspack: {
experiments: { outputModule: true },
externalsType: 'module',
output: {
chunkFormat: 'module',
chunkLoading: 'import',
workerChunkLoading: 'import',
wasmLoading: 'fetch',
library: { type: 'module' },
module: true,
},
resolve: {
conditionNames: ['workerd', 'worker', 'browser', 'import', 'require'],
},
},
},
},
},
plugins: [pluginReactRouter({customServer: true}), pluginReact()],
});
- Configure Wrangler (
wrangler.toml
):
workers_dev = true
name = "my-react-router-worker"
compatibility_date = "2024-11-18"
main = "./build/server/static/js/app.js"
assets = { directory = "./build/client/" }
[vars]
VALUE_FROM_CLOUDFLARE = "Hello from Cloudflare"
- Create Worker Entry (
server/index.ts
):
import { createRequestHandler } from 'react-router';
declare global {
interface CloudflareEnvironment extends Env {}
interface ImportMeta {
env: {
MODE: string;
};
}
}
declare module 'react-router' {
export interface AppLoadContext {
cloudflare: {
env: CloudflareEnvironment;
ctx: ExecutionContext;
};
}
}
import * as serverBuild from 'virtual/react-router/server-build';
const requestHandler = createRequestHandler(serverBuild, import.meta.env.MODE);
export default {
fetch(request, env, ctx) {
return requestHandler(request, {
cloudflare: { env, ctx },
});
},
} satisfies ExportedHandler<CloudflareEnvironment>;
- Update Package Dependencies:
{
"dependencies": {
"@react-router/node": "^7.1.3",
"@react-router/serve": "^7.1.3",
"react-router": "^7.1.3"
},
"devDependencies": {
"@cloudflare/workers-types": "^4.20241112.0",
"@react-router/cloudflare": "^7.1.3",
"@react-router/dev": "^7.1.3",
"wrangler": "^3.106.0"
}
}
- Setup Deployment Scripts (
package.json
):
{
"scripts": {
"build": "rsbuild build",
"deploy": "npm run build && wrangler deploy",
"dev": "rsbuild dev",
"start": "wrangler dev"
}
}
Key Configuration Notes:
- The
workers_dev = true
setting enables deployment to workers.dev subdomain
main
points to your Worker's entry point in the build output
assets
directory specifies where your static client files are located
- Environment variables can be set in the
[vars]
section
- The
compatibility_date
should be kept up to date
- TypeScript types are provided via
@cloudflare/workers-types
- Development can be done locally using
wrangler dev
- Deployment is handled through
wrangler deploy
Development Workflow:
-
Local Development:
npm run dev
npm start
-
Production Deployment:
npm run deploy
Development
The plugin automatically:
- Runs type generation during development and build
- Sets up development server with live reload
- Handles route-based code splitting
- Manages client and server builds
License
MIT