使用 Nitro mono-jsx 实现零配置 JSX 服务端渲染Server Entry 实战指南【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro导读本文以仓库中的 mono-jsx 示例 为核心讲解如何在 Nitro 中利用server.tsx服务器入口Server Entry把 JSX 直接编译为 HTML 响应从而用最少的配置搭建一个 JSX 驱动的服务端渲染页面。读完本文你将掌握 Nitro 对server.tsx的自动检测机制、tsconfig.json中jsxImportSource的配置方法以及 oxc 编译器如何读取该配置完成 JSX 转换的底层原理。从最小示例认识 mono-jsx 集成示例目录 examples/mono-jsx 的 README 用一段极简代码展示了整个集成方式核心文件 server.tsx 全文如下export default () ( html h1Nitro mono-jsx works!/h1 /html );整个集成只需要三步不需要任何 Nitro 配置创建server.tsx文件export default一个返回 JSX 的函数在tsconfig.json中把 JSX 编译器指向mono-jsx详见下文工程配置一节在package.json中声明mono-jsx依赖并运行nitro dev/nitro build。正如原文档所述Nitro 会自动检测server.tsx并使用 mono-jsx 将 JSX 转换为 HTML只要导出的函数返回 JSXNitro 就会把渲染出的 HTML 作为响应返回给客户端。值得注意的是nitro.config.ts 是一个完全空的配置import { defineConfig } from nitro; export default defineConfig({});这印证了零配置的结论JSX 渲染能力不需要任何 Nitro 侧显式声明一切由文件约定与 tsconfig 驱动。Nitro 如何自动检测 server.tsxServer Entry 机制mono-jsx 示例之所以能工作依赖的是 Nitro 的Server Entry服务器入口机制。根据官方文档 Nitro Server Entry该机制的核心规则如下Nitro 默认会在serverDir若设置或项目根目录自动查找server.ts以及.js、.mjs、.mts、.tsx、.jsx等变体server.tsx正是其中之一找到后Nitro 会将其注册为一个 catch-all/**路由即所有未被具体路由匹配的请求都会进入该处理函数特定路由永远优先例如存在routes/api/hello.ts时/api/hello由它处理而/about这类未匹配请求才会落到 server entry在请求生命周期中server entry 运行于路由匹配之后、renderer渲染器 之前参考 Lifecycle 文档。因此把返回 JSX 的函数导出为server.tsx的默认导出就相当于告诉 Nitro所有未被路由处理的请求都渲染这段 JSX 作为 HTML 页面返回。这与创建一个独立页面路由不同——它是一种兜底性的响应逻辑天然适合整站入口、SPA 外壳或框架挂载场景。与 middleware 的区别需要特别澄清server entry 是兜底处理器而非全局中间件。它不会对已被路由处理的请求执行。如果需要在每一个请求包括已匹配路由的请求上执行鉴权、日志、预处理等横切逻辑应使用 middleware如果只是需要在所有未匹配路径上返回 JSX 页面则 server entry即本文的server.tsx方案是正确的选择。工程配置tsconfig 中的 jsxImportSourcemono-jsx 示例能正确编译的关键在 tsconfig.json{ extends: nitro/tsconfig, compilerOptions: { jsx: react-jsx, jsxImportSource: mono-jsx } }两个配置项的作用分别是jsx: react-jsx启用自动运行时automatic runtimeJSX 转换模式。在此模式下源码中的html、h1等 JSX 会被编译为对jsx()/jsxs()工厂函数的调用而不是直接调用React.createElementjsxImportSource: mono-jsx把 JSX 工厂函数的导入来源指向mono-jsx包。编译器会自动生成import { jsx as _jsx } from mono-jsx/jsx-runtime或等价导入由 mono-jsx 的运行时把 JSX 节点树序列化为 HTML 字符串。这就是JSX 转换为 HTML的机制核心JSX 只是语法糖真正决定渲染产物的是jsxImportSource指向的运行时。mono-jsx 提供的运行时负责把元素树拼装成 HTML因此不需要任何浏览器端框架参与。配套工程文件示例还提供了两种运行方式package.json 声明了 npm 脚本与依赖{ type: module, scripts: { dev: nitro dev, build: nitro build }, devDependencies: { mono-jsx: latest, nitro: latest } }pnpm dev或npm run dev启动开发服务器支持热更新修改server.tsx会即时生效pnpm build或npm run build执行生产构建输出可部署的产物。vite.config.ts 提供了以 Vite 插件方式接入 Nitro 的写法import { defineConfig } from vite; import { nitro } from nitro/vite; export default defineConfig({ plugins: [nitro()] });两种方式等价既可以直接使用nitroCLIpackage.json 脚本也可以通过nitro/vite插件把 Nitro 嵌入 Vite 构建管线。底层原理oxc 编译器如何读取 jsxImportSource从源码看Nitro 的构建系统会把tsconfig.json中的 JSX 配置直接传递给 oxc 转换器从而决定 JSX 如何编译。相关实现位于 src/build/rollup/config.tsRollup 构建路径与 src/build/rolldown/config.tsRolldown 构建路径两者的关键逻辑一致const tsc nitro.options.typescript.tsConfig?.compilerOptions; // ... jsx: { runtime: tsc?.jsx react ? classic : automatic, pragma: tsc?.jsxFactory, pragmaFrag: tsc?.jsxFragmentFactory, importSource: tsc?.jsxImportSource, development: nitro.options.dev, // ... }这段代码揭示了完整映射关系tsconfig 配置项oxc jsx 选项作用jsx: react-jsxruntime: automatic使用自动运行时无需手动导入jsx工厂jsxFactorypragma经典模式下的工厂函数名jsxFragmentFactorypragmaFrag经典模式下的 Fragment 工厂名jsxImportSourceimportSource自动运行时从哪个包导入jsx工厂mono-jsx 即由此注入开发模式development: nitro.options.dev开发态下的 JSX 转换差异也就是说mono-jsx 示例的jsxImportSource: mono-jsx会一路流入 oxc 的importSource配置最终使编译产物从mono-jsx导入 JSX 工厂函数完成 HTML 序列化。同时Nitro 构建配置中的扩展名列表见 src/build/config.ts、src/build/vite/plugin.ts 与 src/config/resolvers/paths.ts均包含.tsx、.jsx从解析层面保证了server.tsx能被正常扫描、打包与执行。扩展把 server.tsx 方案接入更复杂的场景掌握了server entry JSX这一模式后可以按需演进1. 结合路由与 APIserver entry 只处理未被路由匹配的请求。你可以在routes/目录下继续编写 API 路由参考 api-routes 示例例如routes/api/hello.ts返回 JSON而server.tsx负责渲染页面——两者互不干扰优先级由 Nitro 的路由匹配保证。2. 自定义 server entry 文件如果不想用默认文件名可在 nitro.config.ts 中指定serverEntryimport { defineConfig } from nitro; export default defineConfig({ serverEntry: ./nitro.server.tsx, });serverEntry也支持对象形式用于显式声明处理器格式export default defineConfig({ serverEntry: { handler: ./server.tsx, format: web, // web默认或 node }, });format为web时要求导出 Web 兼容的fetch(request: Request): Response处理器为node时则期望(req, res)风格的 Node 处理器对应server.node.ts命名约定Nitro 会自动转换。设置serverEntry: false可完全禁用自动检测。3. 返回 undefined 交给渲染器server entry 的返回值语义很重要返回 JSX即返回响应则请求在此结束若函数不返回任何值Nitro 会把请求继续交给 renderer如renderer.ts或index.html处理。因此可以写出先尝试 JSX 渲染、未命中再降级到渲染器的链式逻辑。4. 其他 JSX 运行时对比仓库中还提供了采用不同 JSX 运行时的同类示例 nano-jsx 示例其server.tsx结构与 mono-jsx 几乎一致仅jsxImportSource指向nano-jsx。这印证了该模式的通用性Nitro 并不绑定任何 JSX 运行时只要该运行时提供自动 JSX 工厂就能通过jsxImportSource无缝接入。选择 mono-jsx 还是 nano-jsx取决于你对运行时体积、API 风格和生态的具体偏好。运行与验证在 examples/mono-jsx 目录下执行pnpm install # 安装 nitro 与 mono-jsx 依赖 pnpm dev # 启动开发服务器浏览器访问开发地址即可看到Nitro mono-jsx works!的 HTML 页面。终端会输出 Nitro 检测到 server entry 的提示日志形如Detected server.tsx as server entry.确认自动检测生效。生产环境执行pnpm build产出可部署构建可将产物部署到 Node、Bun、Deno、Cloudflare Workers 等任意支持的目标运行时参见 部署运行时文档。小结Nitro 自动把server.tsx识别为 server entrycatch-all 路由无需任何显式配置tsconfig.json中jsx: react-jsxjsxImportSource: mono-jsx决定 JSX 的编译目标与 HTML 运行时来源Nitro 构建系统Rollup/Rolldown将 tsconfig 的 JSX 选项透传给 oxc 转换器src/build/rollup/config.ts完成从 JSX 到 HTML 的编译链路server entry 是兜底处理器而非全局中间件跨请求横切逻辑应使用 middleware该模式对任意提供 JSX 自动运行时的包通用可轻松替换为 nano-jsx 等其他实现。【免费下载链接】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 + mono-jsx 实现零配置 JSX 服务端渲染（Server Entry 实战指南）
使用 Nitro mono-jsx 实现零配置 JSX 服务端渲染Server Entry 实战指南【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro导读本文以仓库中的 mono-jsx 示例 为核心讲解如何在 Nitro 中利用server.tsx服务器入口Server Entry把 JSX 直接编译为 HTML 响应从而用最少的配置搭建一个 JSX 驱动的服务端渲染页面。读完本文你将掌握 Nitro 对server.tsx的自动检测机制、tsconfig.json中jsxImportSource的配置方法以及 oxc 编译器如何读取该配置完成 JSX 转换的底层原理。从最小示例认识 mono-jsx 集成示例目录 examples/mono-jsx 的 README 用一段极简代码展示了整个集成方式核心文件 server.tsx 全文如下export default () ( html h1Nitro mono-jsx works!/h1 /html );整个集成只需要三步不需要任何 Nitro 配置创建server.tsx文件export default一个返回 JSX 的函数在tsconfig.json中把 JSX 编译器指向mono-jsx详见下文工程配置一节在package.json中声明mono-jsx依赖并运行nitro dev/nitro build。正如原文档所述Nitro 会自动检测server.tsx并使用 mono-jsx 将 JSX 转换为 HTML只要导出的函数返回 JSXNitro 就会把渲染出的 HTML 作为响应返回给客户端。值得注意的是nitro.config.ts 是一个完全空的配置import { defineConfig } from nitro; export default defineConfig({});这印证了零配置的结论JSX 渲染能力不需要任何 Nitro 侧显式声明一切由文件约定与 tsconfig 驱动。Nitro 如何自动检测 server.tsxServer Entry 机制mono-jsx 示例之所以能工作依赖的是 Nitro 的Server Entry服务器入口机制。根据官方文档 Nitro Server Entry该机制的核心规则如下Nitro 默认会在serverDir若设置或项目根目录自动查找server.ts以及.js、.mjs、.mts、.tsx、.jsx等变体server.tsx正是其中之一找到后Nitro 会将其注册为一个 catch-all/**路由即所有未被具体路由匹配的请求都会进入该处理函数特定路由永远优先例如存在routes/api/hello.ts时/api/hello由它处理而/about这类未匹配请求才会落到 server entry在请求生命周期中server entry 运行于路由匹配之后、renderer渲染器 之前参考 Lifecycle 文档。因此把返回 JSX 的函数导出为server.tsx的默认导出就相当于告诉 Nitro所有未被路由处理的请求都渲染这段 JSX 作为 HTML 页面返回。这与创建一个独立页面路由不同——它是一种兜底性的响应逻辑天然适合整站入口、SPA 外壳或框架挂载场景。与 middleware 的区别需要特别澄清server entry 是兜底处理器而非全局中间件。它不会对已被路由处理的请求执行。如果需要在每一个请求包括已匹配路由的请求上执行鉴权、日志、预处理等横切逻辑应使用 middleware如果只是需要在所有未匹配路径上返回 JSX 页面则 server entry即本文的server.tsx方案是正确的选择。工程配置tsconfig 中的 jsxImportSourcemono-jsx 示例能正确编译的关键在 tsconfig.json{ extends: nitro/tsconfig, compilerOptions: { jsx: react-jsx, jsxImportSource: mono-jsx } }两个配置项的作用分别是jsx: react-jsx启用自动运行时automatic runtimeJSX 转换模式。在此模式下源码中的html、h1等 JSX 会被编译为对jsx()/jsxs()工厂函数的调用而不是直接调用React.createElementjsxImportSource: mono-jsx把 JSX 工厂函数的导入来源指向mono-jsx包。编译器会自动生成import { jsx as _jsx } from mono-jsx/jsx-runtime或等价导入由 mono-jsx 的运行时把 JSX 节点树序列化为 HTML 字符串。这就是JSX 转换为 HTML的机制核心JSX 只是语法糖真正决定渲染产物的是jsxImportSource指向的运行时。mono-jsx 提供的运行时负责把元素树拼装成 HTML因此不需要任何浏览器端框架参与。配套工程文件示例还提供了两种运行方式package.json 声明了 npm 脚本与依赖{ type: module, scripts: { dev: nitro dev, build: nitro build }, devDependencies: { mono-jsx: latest, nitro: latest } }pnpm dev或npm run dev启动开发服务器支持热更新修改server.tsx会即时生效pnpm build或npm run build执行生产构建输出可部署的产物。vite.config.ts 提供了以 Vite 插件方式接入 Nitro 的写法import { defineConfig } from vite; import { nitro } from nitro/vite; export default defineConfig({ plugins: [nitro()] });两种方式等价既可以直接使用nitroCLIpackage.json 脚本也可以通过nitro/vite插件把 Nitro 嵌入 Vite 构建管线。底层原理oxc 编译器如何读取 jsxImportSource从源码看Nitro 的构建系统会把tsconfig.json中的 JSX 配置直接传递给 oxc 转换器从而决定 JSX 如何编译。相关实现位于 src/build/rollup/config.tsRollup 构建路径与 src/build/rolldown/config.tsRolldown 构建路径两者的关键逻辑一致const tsc nitro.options.typescript.tsConfig?.compilerOptions; // ... jsx: { runtime: tsc?.jsx react ? classic : automatic, pragma: tsc?.jsxFactory, pragmaFrag: tsc?.jsxFragmentFactory, importSource: tsc?.jsxImportSource, development: nitro.options.dev, // ... }这段代码揭示了完整映射关系tsconfig 配置项oxc jsx 选项作用jsx: react-jsxruntime: automatic使用自动运行时无需手动导入jsx工厂jsxFactorypragma经典模式下的工厂函数名jsxFragmentFactorypragmaFrag经典模式下的 Fragment 工厂名jsxImportSourceimportSource自动运行时从哪个包导入jsx工厂mono-jsx 即由此注入开发模式development: nitro.options.dev开发态下的 JSX 转换差异也就是说mono-jsx 示例的jsxImportSource: mono-jsx会一路流入 oxc 的importSource配置最终使编译产物从mono-jsx导入 JSX 工厂函数完成 HTML 序列化。同时Nitro 构建配置中的扩展名列表见 src/build/config.ts、src/build/vite/plugin.ts 与 src/config/resolvers/paths.ts均包含.tsx、.jsx从解析层面保证了server.tsx能被正常扫描、打包与执行。扩展把 server.tsx 方案接入更复杂的场景掌握了server entry JSX这一模式后可以按需演进1. 结合路由与 APIserver entry 只处理未被路由匹配的请求。你可以在routes/目录下继续编写 API 路由参考 api-routes 示例例如routes/api/hello.ts返回 JSON而server.tsx负责渲染页面——两者互不干扰优先级由 Nitro 的路由匹配保证。2. 自定义 server entry 文件如果不想用默认文件名可在 nitro.config.ts 中指定serverEntryimport { defineConfig } from nitro; export default defineConfig({ serverEntry: ./nitro.server.tsx, });serverEntry也支持对象形式用于显式声明处理器格式export default defineConfig({ serverEntry: { handler: ./server.tsx, format: web, // web默认或 node }, });format为web时要求导出 Web 兼容的fetch(request: Request): Response处理器为node时则期望(req, res)风格的 Node 处理器对应server.node.ts命名约定Nitro 会自动转换。设置serverEntry: false可完全禁用自动检测。3. 返回 undefined 交给渲染器server entry 的返回值语义很重要返回 JSX即返回响应则请求在此结束若函数不返回任何值Nitro 会把请求继续交给 renderer如renderer.ts或index.html处理。因此可以写出先尝试 JSX 渲染、未命中再降级到渲染器的链式逻辑。4. 其他 JSX 运行时对比仓库中还提供了采用不同 JSX 运行时的同类示例 nano-jsx 示例其server.tsx结构与 mono-jsx 几乎一致仅jsxImportSource指向nano-jsx。这印证了该模式的通用性Nitro 并不绑定任何 JSX 运行时只要该运行时提供自动 JSX 工厂就能通过jsxImportSource无缝接入。选择 mono-jsx 还是 nano-jsx取决于你对运行时体积、API 风格和生态的具体偏好。运行与验证在 examples/mono-jsx 目录下执行pnpm install # 安装 nitro 与 mono-jsx 依赖 pnpm dev # 启动开发服务器浏览器访问开发地址即可看到Nitro mono-jsx works!的 HTML 页面。终端会输出 Nitro 检测到 server entry 的提示日志形如Detected server.tsx as server entry.确认自动检测生效。生产环境执行pnpm build产出可部署构建可将产物部署到 Node、Bun、Deno、Cloudflare Workers 等任意支持的目标运行时参见 部署运行时文档。小结Nitro 自动把server.tsx识别为 server entrycatch-all 路由无需任何显式配置tsconfig.json中jsx: react-jsxjsxImportSource: mono-jsx决定 JSX 的编译目标与 HTML 运行时来源Nitro 构建系统Rollup/Rolldown将 tsconfig 的 JSX 选项透传给 oxc 转换器src/build/rollup/config.ts完成从 JSX 到 HTML 的编译链路server entry 是兜底处理器而非全局中间件跨请求横切逻辑应使用 middleware该模式对任意提供 JSX 自动运行时的包通用可轻松替换为 nano-jsx 等其他实现。【免费下载链接】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），仅供参考