Nx Next.js 库生成实战创建库与导出 React Server Components【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx导读nx/next为 Nx 工作区提供了一整套 Next.js 项目生成器其中library生成器用于创建可供应用复用的 Next.js 库。与普通的 React 库不同Next.js 库自带一个额外的src/server.ts入口专门用于导出 React Server ComponentsRSC从而避免客户端组件与服务器组件混用导致运行时错误。本文基于 packages/next/docs/library-examples.md 展开结合 library 生成器源码 与 schema.json完整讲解库的创建方式、常用配置项以及 RSC 双入口机制背后的实现原理。读完本文你将能够熟练地在 Nx 工作区中创建任意路径下的 Next.js 库并正确组织客户端组件与服务器组件的导出。创建库的基本命令nx/next:library生成器的核心用法与nx/react:library保持一致但输出额外包含server入口点和 Next.js 类型声明详见 schema.json 的描述。创建新库在 Nx 工作区根目录执行以下命令即可在默认位置生成一个名为my-lib的库nx g lib libs/my-lib命令执行后nx/next会依次执行内部的初始化流程调用链见 library.ts调用nx/js的initGenerator完成 JS/TS 工具链初始化调用nextInitGenerator完成 Next.js 相关依赖与配置初始化复用nx/react的libraryGenerator生成 React 库骨架。也就是说Next.js 库是 React 库的超集——它继承了 React 库的全部结构再叠加 Next.js 专属的入口与类型配置。生成器还会自动向tsconfig.lib.json的compilerOptions.types中追加next与nx/next/typings/image.d.tslibrary.ts确保库内的 Next.js 代码如Image组件、样式导入获得正确的类型支持。这一点也有对应的单元测试验证见 library.spec.ts。在指定目录下创建库将directory参数也支持别名dir指向一个子目录即可把库生成在嵌套路径中nx g lib libs/shared/my-lib上面的命令会在libs/shared/my-lib位置生成库。directory是生成器的位置参数$default指定为 argv 的第一个参数它会与name一起经由determineProjectNameAndRootOptions推导出最终的projectRoot与importPath见 normalize-options.ts。默认情况下导入路径由目录结构推导而来例如libs/shared/my-lib对应的导入名通常为proj/shared/my-lib其中proj为工作区名可通过--importPath显式覆盖。常用配置项速查nx/next:library的参数与nx/react:library对齐测试 library.spec.ts 专门校验了两者的 schema 保持同步核心选项如下选项类型默认值说明directorystring—库所在的目录必填作为位置参数namestring—库名支持scope/name形式stylestringcss样式文件格式可选css、scss、nonebundlerstringnone打包器可选none、vite、rollupnone表示不可构建linterstring工作区默认静态检查工具可选eslint、oxlint、noneunitTestRunnerstringnone单元测试运行器可选vitest、jest、noneinSourceTestsbooleanfalse使用 Vitest 时把测试内联到源码文件import.meta.vitest而非生成独立 spec 文件importPathstring自动推导库的导入路径如myorg/my-awesome-libcomponentbooleantrue是否生成默认组件jsbooleanfalse生成 JavaScript 而非 TypeScript 文件globalCssbooleanfalse为true时使用全局 CSS 而非 CSS Modulesstrictbooleantrue是否启用 tsconfig 严格模式compilerstringbabel编译器可选babel、swcbuildablebooleanfalse已弃用生成可构建库请改用bundlerpublishablebooleanfalse生成可发布库routingboolean—生成带路由的库配合appProject使用appProjectstring—要将库路由挂载到的应用项目tagsstring—为库添加标签用于约束依赖的 lint 规则skipTsConfigbooleanfalse不更新tsconfig.jsonskipPackageJsonbooleanfalse不向package.json添加依赖enableTypedLintingbooleanfalse启用类型感知的 ESLint 检查为性能默认关闭一个覆盖常见场景的完整示例nx g lib libs/shared/ui --stylescss --bundlervite --unitTestRunnervitest --importPathmyorg/ui --tagsscope:shared,type:ui生成器会为带单元测试运行器的库自动安装testing-library/react与testing-library/dom依赖选择swc编译器时还会自动加入swc/corelibrary.ts测试见 library.spec.ts。导出 React Server Components双入口机制Next.js 库区别于普通 React 库的核心在于其第二个入口src/server.ts。这一点在原文档中有明确说明生成器源码也给出了直接注释从src/index.ts导出 RSC 会把整个文件标记为 server-only当客户端组件引入该文件时就会抛错见 library.ts相关历史问题见 Nx issue #15830 的注释。为什么需要单独的 server 入口在 React Server Components 架构下客户端组件带use client指令或需要交互逻辑与服务器组件可异步访问数据库、API的执行环境完全不同。若将两者混在同一个入口文件导出服务器组件会要求调用方运行在服务器上下文客户端组件一旦 import 该文件就会把 server-only 代码带入客户端 bundle导致构建或运行时错误。因此生成器在创建库时生成了两个职责明确的入口文件src/index.ts导出 React 客户端组件带use client指令的组件及其他非服务器工具函数src/server.ts专门导出 React 服务器组件。生成器写入的src/index.ts顶部注释即为“Use this file to export React client components (e.g. those with use client directive) or other non-server utilities”src/server.ts则写入“Use this file to export React server components”并默认导出一个HelloServer异步组件library.ts。应用中的消费方式原文档给出了在应用中使用库的标准姿势客户端组件从库根路径导入服务器组件从/server子路径导入// apps/my-app/app/page.tsx import { MyComponent } from myorg/my-lib; import { HelloServer } from myorg/my-lib/server;要让myorg/my-lib/server这条子路径在开发与构建时都能正确解析生成器会同步完成三处接线测试断言见 library.spec.tstsconfig 路径映射在tsconfig.base.json的compilerOptions.paths中追加proj/my-lib/server - ./my-lib/src/server.tsVite 多入口配置使用bundlervite时把vite.config.mts中单一的entry: src/index.ts改写为{ index: src/index.ts, server: src/server.ts }多入口对象并将fileName改为按入口名输出的函数update-vite-config.tspackage.json exports向库的package.json添加./server导出映射指向./dist/server.js/./dist/server.d.ts测试见 library.spec.ts。在 TS Solution 工作区使用referencescustomConditions的现代配置中非可构建库会在package.json的exports[./server]里直接映射到源码./src/server.ts并通过自定义 condition 指向开发源码可构建库则映射到dist产物library.ts。使用约束与最佳实践结合原文档与源码可以总结出以下实践准则客户端组件与纯工具函数一律放在src/index.ts中导出服务器组件如需要直接访问数据库、密钥或服务端 API 的异步组件放在src/server.ts中导出不要在src/index.ts中导出任何服务器组件否则会污染整个入口的模块边界应用侧按需选择导入路径页面与客户端组件引用myorg/my-lib仅服务端代码引用myorg/my-lib/server。小结nx/next的 library 生成器把创建库与RSC 正确导出这两件事自动化了一条nx g lib命令即可在任意目录生成结构完整的 Next.js 库同时自动搭建src/index.ts客户端与src/server.ts服务器组件的双入口并完成 tsconfig 路径、Vite 构建入口与 package.json exports 的全部接线。理解这套机制后你可以在 Nx 工作区中放心地按客户端/服务器维度组织库的导出边界避免 RSC 混用带来的构建陷阱。更多命令示例可参考同目录下的 application-examples.md、component-examples.md 与 page-examples.md深入理解生成器实现可阅读 library.ts 及其配套测试 library.spec.ts。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考