使用 Nitro Vite 构建 React Router 全栈 SSR 应用【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro导读本文以 Nitro 官方示例 examples/vite-ssr-react-router 为核心讲解如何将 React Router框架模式 / framework mode与 Nitro 深度集成在同一个 Vite 生命周期内开发、构建前端与后端由 Nitro 负责运行 React Router 的服务端渲染产物并同时承载 API 路由、静态资源与生产部署。读完本文你将掌握完整的工程配置方法Vite 插件编排、输出目录对齐、SSR 入口编写、路由声明以及这套架构在开发与生产环境中的底层工作原理。概览一套 Vite 生命周期一个生产服务器React Router 是一个声明式路由框架其 8.x 版本提供了完整的 SSR / 流式渲染能力但服务端运行环境Node、Workers、Serverless 等的差异需要由上层工具消化。Nitro 恰好补足这一层它扫描服务端目录、生成与运行时无关的服务器构建并支持通过 preset 一键输出到各类部署平台。两者结合的完整步骤可以归纳为五步在 Vite 配置中同时添加 React Router 与 Nitro 插件让 Nitro 的服务端输出与 React Router 的客户端构建产物保持目录对齐用 React Router 的createRequestHandler编写一个 fetch 兼容的 SSR 处理器在server/routes/下添加 Nitro 原生 API 路由通过app/routes.ts声明 React Router 的应用路由。项目目录结构来自 examples/vite-ssr-react-router其中public/与logos/为静态资源app/ routes/home.tsx # 页面路由组件 app.css # Tailwind CSS 入口 root.tsx # 根布局、文档外壳与错误边界 routes.ts # React Router 路由声明 server/ routes/health.get.ts # Nitro API 路由/health ssr.ts # SSR 处理器fetch 入口 react-router.config.ts # React Router 框架配置 vite.config.ts # 统一构建入口这套架构的核心收益示例首页 app/routes/home.tsx 中有直接展示可移植部署用 preset 将同一套应用构建到 Node、Workers 与 Serverless 运行时后端原语可直接使用 Nitro 的缓存、存储、数据库、路由规则与定时任务单一生产服务器SSR、客户端静态资源与 API 路由从同一个生产输出提供单一 Vite 生命周期React Router 前端与 Nitro 后端一起开发、一起构建进程内请求loader 中调用 Nitro 路由无需走网络往返零胶水路由先处理服务端路由未匹配时自动落到 React Router SSR。1. 配置 Vite三种插件协同先看工程根目录的 vite.config.tsimport { reactRouter } from react-router/dev/vite; import tailwindcss from tailwindcss/vite; import { defineConfig } from vite; import { nitro } from nitro/vite; import reactRouterConfig from ./react-router.config; export default defineConfig({ plugins: [ tailwindcss(), reactRouter(), nitro({ serverDir: ./server, output: { dir: reactRouterConfig.buildDirectory, serverDir: ${reactRouterConfig.buildDirectory}/server, publicDir: ${reactRouterConfig.buildDirectory}/client, }, }), ], resolve: { tsconfigPaths: true, }, environments: { ssr: { build: { rollupOptions: { input: ./server/ssr.ts } } }, }, });插件各自的分工tailwindcss/vite负责样式编译入口样式见 app/app.cssimport tailwindcss并通过theme定义了 Inter 字体族同时处理亮/暗色模式下的color-schemereactRouter()来自react-router/dev/vite创建ssr环境把浏览器端资源构建到build/client并生成virtual:react-router/server-build服务端构建nitro()来自nitro/vite入口导出见 src/vite.ts实现位于 src/build/vite/plugin.ts扫描serverDir目录识别 Nitro 路由将生产服务器构建输出到build/server。三个关键配置点serverDir: ./server指定 Nitro 扫描服务端代码的目录示例中的 server/ssr.ts 与server/routes/都位于此目录下输出目录对齐output.dir直接复用react-router.config.ts中的buildDirectory即buildserverDir与publicDir分别指向build/server与build/client确保两端产物互不覆盖environments.ssr.build.rollupOptions.input指向./server/ssr.ts让 Vite 把自定义的 SSR 入口纳入构建。resolve.tsconfigPaths: true启用基于 tsconfig 的路径别名解析配合 tsconfig.json 中的~/*: [./app/*]可以在代码里用~/前缀导入app/下的模块。该 tsconfig 还通过extends: nitro/tsconfig继承 Nitro 的推荐编译选项并将.react-router/types/**/*加入 include以支持 React Router 生成的类型rootDirs里也加入了.react-router/types。2. 配置 React Router开启 SSR 并对齐构建目录react-router.config.ts 是 React Router 框架模式的唯一配置入口import type { Config } from react-router/dev/config; export default { // Config options... // Server-side render by default, to enable SPA mode set this to false ssr: true, buildDirectory: build, } satisfies Config;ssr: true默认开启服务端渲染若改成false则退化为纯 SPA 模式此时服务端只负责托管静态资源与 APIbuildDirectory: build必须与 Vite 配置中 Nitro 的output.dir保持一致这是前后端产物在同一个输出目录下共存的基石。开启 SSR 后React Router 会同时产出两部分关键产物通过virtual:react-router/server-build暴露的服务端构建供渲染匹配路由以及客户端用于 hydration 的静态资源输出到build/client。3. 编写 SSR 处理器把请求委托给 React Router核心文件是 server/ssr.ts全文只有 8 行import { createRequestHandler } from react-router; export default { fetch: createRequestHandler( () import(virtual:react-router/server-build), import.meta.env.MODE ), };它的工作方式默认导出是一个 Webfetch兼容处理器{ fetch }形状这也是 Nitro 约定的入口形态因此能被 Nitro 的 Vitessr服务在开发与生产环境中统一调用createRequestHandler来自react-router接收两个参数一个懒加载函数返回 React Router 生成的服务端构建virtual:react-router/server-build以及当前环境模式import.meta.env.MODE如development/production由 Vite 注入请求到达时Nitro 把请求交给该 handler由它加载匹配的路由模块完成 SSR 渲染并返回响应。从源码结构看Nitro 的 Vite 插件层src/build/vite/plugin.ts、src/build/vite/services.ts负责将这类 fetch handler 挂载为服务的处理入口而开发与生产分别由 src/build/vite/dev.ts 与 src/build/vite/prod.ts 承担。4. 添加 Nitro 服务端路由API 与 SSR 无缝共存在server/routes/目录下按文件路径约定声明路由。示例提供了一个健康检查接口 server/routes/health.get.tsimport { defineHandler } from nitro; export default defineHandler(() { return { status: OK }; });文件名health.get.ts中的.get表示仅匹配 HTTP GET 方法因此该路由可通过GET /health访问defineHandler是 Nitro 提供的路由处理器工具定义于 src/runtime/nitro.ts返回对象会被自动序列化为 JSON 响应路由优先级Nitro 服务端路由先于 SSR 服务被处理——当请求路径命中 Nitro 路由时直接返回未命中时再自动落到 React Router 的 SSR handler这正是零胶水路由routing without glue的含义也是示例首页 feature 列表中强调的能力。目录约定小结文件路径路由说明server/routes/health.get.tsGET /healthAPI 路由命中后不再进入 SSRserver/routes/index.tsGET /根路径 API 路由server/middleware/*.ts全局中间件每个请求都会执行server/routes/**/*.ts通配其余未匹配路径最终落入 React Router SSR5. 声明 React Router 路由在app/下通过 app/routes.ts 声明应用路由import { type RouteConfig, index } from react-router/dev/routes; export default [index(routes/home.tsx)] satisfies RouteConfig;该配置将routes/home.tsx注册为索引路由渲染在/路径。React Router 会据此生成路由类型types/home并配合root.tsx的布局完成 SSR。根布局与错误边界app/root.tsx 定义了完整的 HTML 文档外壳links导出预连接 Google Fonts 并加载 Inter 字体LinksFunctionLayout组件输出html、head中的Meta /、Links /以及body中的ScrollRestoration /与Scripts /——这些是 React Router 注入 SSR 标记与 hydration 脚本的挂载点ErrorBoundary使用isRouteErrorResponse区分 404 与一般错误开发模式下额外输出错误堆栈生产环境则隐藏细节避免敏感信息泄露。6. 从 package.json 看完整工程闭环package.json 给出了完整的脚本与依赖体系{ scripts: { build: vite build, dev: vite dev, start: node ./build/server/index.mjs, typegen: react-router typegen } }devvite dev启动开发服务器React Router 前端与 Nitro 后端共用同一 Vite 开发实例支持 HMRbuildvite build一次性产出客户端资源build/client与 Nitro 生产服务器build/serverstartnode ./build/server/index.mjs直接运行 Nitro 生成的生产服务器同时提供 SSR、静态资源与 APItypegen生成 React Router 的路由类型声明配合 tsconfig 中的.react-router/types。依赖方面运行时依赖react、react-dom、react-router与react-router/node提供 Node 平台适配与 isbot 支持开发依赖包括react-router/dev框架模式插件、nitro、vite、tailwindcss以及 TypeScript 相关类型包。当前示例锁定的版本为 React Router /react-router/*8.1、React 19.2、Tailwind CSS 4.3 与 TypeScript 6以 package.json 实际声明为准。7. 请求链路与部署综合以上配置一次页面请求的完整链路为浏览器请求 / → Nitro 服务器build/server/index.mjs → 命中 Nitro 路由(如 /health) → 返回 API 响应 → 未命中 → SSR 服务调用 server/ssr.ts 的 fetch handler → createRequestHandler 加载 virtual:react-router/server-build → 匹配 app/routes.ts 中的路由并渲染 HTML → 返回含 hydration 脚本的完整文档得益于 Nitro 的 preset 体系同一个build产物可以通过 preset 输出到 Node、Cloudflare Workers、Deno、Netlify、Vercel 等运行时详见 docs/2.deploySSR 逻辑本身无需改动——这正是同一套应用随处部署的核心价值。如果希望进一步控制目录选项可参考 docs/1.docs/50.configuration.md 中的 directory options 说明。小结本文完整复现了 Nitro React Router 全栈 SSR 的官方方案通过 Vite 插件的组合reactRouternitro、构建目录的对齐build/build/server/build/client、fetch 兼容的 SSR 入口server/ssr.ts以及 Nitro 路由优先的请求策略实现了一个生命周期内同时完成前端、后端构建与部署的架构。示例代码可直接在 examples/vite-ssr-react-router 中查看运行也可对照本文步骤从零搭建。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Nitro + Vite 构建 React Router 全栈 SSR 应用
使用 Nitro Vite 构建 React Router 全栈 SSR 应用【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro导读本文以 Nitro 官方示例 examples/vite-ssr-react-router 为核心讲解如何将 React Router框架模式 / framework mode与 Nitro 深度集成在同一个 Vite 生命周期内开发、构建前端与后端由 Nitro 负责运行 React Router 的服务端渲染产物并同时承载 API 路由、静态资源与生产部署。读完本文你将掌握完整的工程配置方法Vite 插件编排、输出目录对齐、SSR 入口编写、路由声明以及这套架构在开发与生产环境中的底层工作原理。概览一套 Vite 生命周期一个生产服务器React Router 是一个声明式路由框架其 8.x 版本提供了完整的 SSR / 流式渲染能力但服务端运行环境Node、Workers、Serverless 等的差异需要由上层工具消化。Nitro 恰好补足这一层它扫描服务端目录、生成与运行时无关的服务器构建并支持通过 preset 一键输出到各类部署平台。两者结合的完整步骤可以归纳为五步在 Vite 配置中同时添加 React Router 与 Nitro 插件让 Nitro 的服务端输出与 React Router 的客户端构建产物保持目录对齐用 React Router 的createRequestHandler编写一个 fetch 兼容的 SSR 处理器在server/routes/下添加 Nitro 原生 API 路由通过app/routes.ts声明 React Router 的应用路由。项目目录结构来自 examples/vite-ssr-react-router其中public/与logos/为静态资源app/ routes/home.tsx # 页面路由组件 app.css # Tailwind CSS 入口 root.tsx # 根布局、文档外壳与错误边界 routes.ts # React Router 路由声明 server/ routes/health.get.ts # Nitro API 路由/health ssr.ts # SSR 处理器fetch 入口 react-router.config.ts # React Router 框架配置 vite.config.ts # 统一构建入口这套架构的核心收益示例首页 app/routes/home.tsx 中有直接展示可移植部署用 preset 将同一套应用构建到 Node、Workers 与 Serverless 运行时后端原语可直接使用 Nitro 的缓存、存储、数据库、路由规则与定时任务单一生产服务器SSR、客户端静态资源与 API 路由从同一个生产输出提供单一 Vite 生命周期React Router 前端与 Nitro 后端一起开发、一起构建进程内请求loader 中调用 Nitro 路由无需走网络往返零胶水路由先处理服务端路由未匹配时自动落到 React Router SSR。1. 配置 Vite三种插件协同先看工程根目录的 vite.config.tsimport { reactRouter } from react-router/dev/vite; import tailwindcss from tailwindcss/vite; import { defineConfig } from vite; import { nitro } from nitro/vite; import reactRouterConfig from ./react-router.config; export default defineConfig({ plugins: [ tailwindcss(), reactRouter(), nitro({ serverDir: ./server, output: { dir: reactRouterConfig.buildDirectory, serverDir: ${reactRouterConfig.buildDirectory}/server, publicDir: ${reactRouterConfig.buildDirectory}/client, }, }), ], resolve: { tsconfigPaths: true, }, environments: { ssr: { build: { rollupOptions: { input: ./server/ssr.ts } } }, }, });插件各自的分工tailwindcss/vite负责样式编译入口样式见 app/app.cssimport tailwindcss并通过theme定义了 Inter 字体族同时处理亮/暗色模式下的color-schemereactRouter()来自react-router/dev/vite创建ssr环境把浏览器端资源构建到build/client并生成virtual:react-router/server-build服务端构建nitro()来自nitro/vite入口导出见 src/vite.ts实现位于 src/build/vite/plugin.ts扫描serverDir目录识别 Nitro 路由将生产服务器构建输出到build/server。三个关键配置点serverDir: ./server指定 Nitro 扫描服务端代码的目录示例中的 server/ssr.ts 与server/routes/都位于此目录下输出目录对齐output.dir直接复用react-router.config.ts中的buildDirectory即buildserverDir与publicDir分别指向build/server与build/client确保两端产物互不覆盖environments.ssr.build.rollupOptions.input指向./server/ssr.ts让 Vite 把自定义的 SSR 入口纳入构建。resolve.tsconfigPaths: true启用基于 tsconfig 的路径别名解析配合 tsconfig.json 中的~/*: [./app/*]可以在代码里用~/前缀导入app/下的模块。该 tsconfig 还通过extends: nitro/tsconfig继承 Nitro 的推荐编译选项并将.react-router/types/**/*加入 include以支持 React Router 生成的类型rootDirs里也加入了.react-router/types。2. 配置 React Router开启 SSR 并对齐构建目录react-router.config.ts 是 React Router 框架模式的唯一配置入口import type { Config } from react-router/dev/config; export default { // Config options... // Server-side render by default, to enable SPA mode set this to false ssr: true, buildDirectory: build, } satisfies Config;ssr: true默认开启服务端渲染若改成false则退化为纯 SPA 模式此时服务端只负责托管静态资源与 APIbuildDirectory: build必须与 Vite 配置中 Nitro 的output.dir保持一致这是前后端产物在同一个输出目录下共存的基石。开启 SSR 后React Router 会同时产出两部分关键产物通过virtual:react-router/server-build暴露的服务端构建供渲染匹配路由以及客户端用于 hydration 的静态资源输出到build/client。3. 编写 SSR 处理器把请求委托给 React Router核心文件是 server/ssr.ts全文只有 8 行import { createRequestHandler } from react-router; export default { fetch: createRequestHandler( () import(virtual:react-router/server-build), import.meta.env.MODE ), };它的工作方式默认导出是一个 Webfetch兼容处理器{ fetch }形状这也是 Nitro 约定的入口形态因此能被 Nitro 的 Vitessr服务在开发与生产环境中统一调用createRequestHandler来自react-router接收两个参数一个懒加载函数返回 React Router 生成的服务端构建virtual:react-router/server-build以及当前环境模式import.meta.env.MODE如development/production由 Vite 注入请求到达时Nitro 把请求交给该 handler由它加载匹配的路由模块完成 SSR 渲染并返回响应。从源码结构看Nitro 的 Vite 插件层src/build/vite/plugin.ts、src/build/vite/services.ts负责将这类 fetch handler 挂载为服务的处理入口而开发与生产分别由 src/build/vite/dev.ts 与 src/build/vite/prod.ts 承担。4. 添加 Nitro 服务端路由API 与 SSR 无缝共存在server/routes/目录下按文件路径约定声明路由。示例提供了一个健康检查接口 server/routes/health.get.tsimport { defineHandler } from nitro; export default defineHandler(() { return { status: OK }; });文件名health.get.ts中的.get表示仅匹配 HTTP GET 方法因此该路由可通过GET /health访问defineHandler是 Nitro 提供的路由处理器工具定义于 src/runtime/nitro.ts返回对象会被自动序列化为 JSON 响应路由优先级Nitro 服务端路由先于 SSR 服务被处理——当请求路径命中 Nitro 路由时直接返回未命中时再自动落到 React Router 的 SSR handler这正是零胶水路由routing without glue的含义也是示例首页 feature 列表中强调的能力。目录约定小结文件路径路由说明server/routes/health.get.tsGET /healthAPI 路由命中后不再进入 SSRserver/routes/index.tsGET /根路径 API 路由server/middleware/*.ts全局中间件每个请求都会执行server/routes/**/*.ts通配其余未匹配路径最终落入 React Router SSR5. 声明 React Router 路由在app/下通过 app/routes.ts 声明应用路由import { type RouteConfig, index } from react-router/dev/routes; export default [index(routes/home.tsx)] satisfies RouteConfig;该配置将routes/home.tsx注册为索引路由渲染在/路径。React Router 会据此生成路由类型types/home并配合root.tsx的布局完成 SSR。根布局与错误边界app/root.tsx 定义了完整的 HTML 文档外壳links导出预连接 Google Fonts 并加载 Inter 字体LinksFunctionLayout组件输出html、head中的Meta /、Links /以及body中的ScrollRestoration /与Scripts /——这些是 React Router 注入 SSR 标记与 hydration 脚本的挂载点ErrorBoundary使用isRouteErrorResponse区分 404 与一般错误开发模式下额外输出错误堆栈生产环境则隐藏细节避免敏感信息泄露。6. 从 package.json 看完整工程闭环package.json 给出了完整的脚本与依赖体系{ scripts: { build: vite build, dev: vite dev, start: node ./build/server/index.mjs, typegen: react-router typegen } }devvite dev启动开发服务器React Router 前端与 Nitro 后端共用同一 Vite 开发实例支持 HMRbuildvite build一次性产出客户端资源build/client与 Nitro 生产服务器build/serverstartnode ./build/server/index.mjs直接运行 Nitro 生成的生产服务器同时提供 SSR、静态资源与 APItypegen生成 React Router 的路由类型声明配合 tsconfig 中的.react-router/types。依赖方面运行时依赖react、react-dom、react-router与react-router/node提供 Node 平台适配与 isbot 支持开发依赖包括react-router/dev框架模式插件、nitro、vite、tailwindcss以及 TypeScript 相关类型包。当前示例锁定的版本为 React Router /react-router/*8.1、React 19.2、Tailwind CSS 4.3 与 TypeScript 6以 package.json 实际声明为准。7. 请求链路与部署综合以上配置一次页面请求的完整链路为浏览器请求 / → Nitro 服务器build/server/index.mjs → 命中 Nitro 路由(如 /health) → 返回 API 响应 → 未命中 → SSR 服务调用 server/ssr.ts 的 fetch handler → createRequestHandler 加载 virtual:react-router/server-build → 匹配 app/routes.ts 中的路由并渲染 HTML → 返回含 hydration 脚本的完整文档得益于 Nitro 的 preset 体系同一个build产物可以通过 preset 输出到 Node、Cloudflare Workers、Deno、Netlify、Vercel 等运行时详见 docs/2.deploySSR 逻辑本身无需改动——这正是同一套应用随处部署的核心价值。如果希望进一步控制目录选项可参考 docs/1.docs/50.configuration.md 中的 directory options 说明。小结本文完整复现了 Nitro React Router 全栈 SSR 的官方方案通过 Vite 插件的组合reactRouternitro、构建目录的对齐build/build/server/build/client、fetch 兼容的 SSR 入口server/ssr.ts以及 Nitro 路由优先的请求策略实现了一个生命周期内同时完成前端、后端构建与部署的架构。示例代码可直接在 examples/vite-ssr-react-router 中查看运行也可对照本文步骤从零搭建。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考