Reselect 文档站工程实践website/ 目录 Docusaurus 站点的开发、构建与部署全流程【免费下载链接】reselectSelector library for Redux项目地址: https://gitcode.com/gh_mirrors/re/reselectReselect 的官方文档站位于website/目录基于 Docusaurus 构建覆盖安装、本地开发、静态构建与生产部署的完整工程链路。本文以 website/README.md 为主线结合package.json脚本、Docusaurus 配置和文档示例注入脚本的真实实现讲清楚这个文档站“如何跑起来、如何构建、如何上线”以及它在启动前自动编译文档代码示例的底层机制。website/ 是一个独立的 pnpm 项目理解这个文档站工程的第一步是明确它和仓库主体的关系仓库根目录 pnpm-workspace.yaml 中明确注明website/是一个独立的 pnpm 项目拥有自己的 lockfile 和自己的pnpm-workspace.yaml并不属于根 workspace 的成员包仓库根 package.json 中提供了转发脚本可以直接在根目录操作文档站docs:start、docs:build、docs:clear、docs:serve它们分别通过pnpm --dir website run start等命令转发到website/目录执行website/package.json 声明了engines.node 18和packageManager: pnpm11.23.0即本地运行文档站需要 Node 18 以上、pnpm 11.x 环境。依赖方面website/package.json 使用docusaurus/core与docusaurus/preset-classic3.10.2 版本、React 19并额外引入了getcanary/docusaurus-theme-search-pagefind主题插件用于全文搜索prism-react-renderer用于代码高亮。README 中提到的pnpm install就是在这个目录下执行安装的是这份独立 lockfile 对应的依赖树。站点核心配置docusaurus.config.ts 与 sidebars.tswebsite/docusaurus.config.ts 定义了站点的身份与行为几个关键点配置项取值作用title/taglineReselect/A memoized selector library for Redux站点标题与副标题也用于首页 hero 区域urlhttps://reselect.js.org生产环境 URLbaseUrl/站点部署在域名根路径下organizationName/projectNamereduxjs/reselectGitHub Pages 部署配置见后文部署章节onBrokenLinksthrow构建时发现失效链接直接报错保证链接质量i18n仅en当前只维护英文文档文档插件classic preset 的docs配置了sidebarPath: ./sidebars.ts、showLastUpdateTime: true、routeBasePath: /文档直接挂在站点根路径以及指向仓库编辑入口的editUrl。站点还通过themes数组加载了 Pagefind 搜索主题并在themeConfig中启用了 Monokai 代码主题prism.theme: require(./monokaiTheme.js)对应 website/monokaiTheme.js。website/sidebars.ts 采用显式定义而非目录自动扫描生成侧边栏组织为四个分组Introductiongetting-started、how-does-reselect-work、v5-summary、APIcreateSelector、createSelectorCreator、createStructuredSelector、development-only-checks以及 lruMemoize、weakMapMemoize 两个 Memoization Functions 子项、Using Reselectbest-practices、common-mistakes、handling-empty-array-results以及 FAQ、external-references、related-projects 三篇独立文档。侧边栏中的docId对应 website/docs/ 目录下的实际文件修改文档结构时需同步维护这份配置。安装与本地开发pnpm start 到底做了什么README 给出的开发流程是两条命令# 安装依赖 $ pnpm install # 启动本地开发服务器自动打开浏览器 $ pnpm startpnpm start会启动 Docusaurus 开发服务器多数改动无需重启即可实时生效。但值得注意的是website/package.json 中start并非直接执行docusaurus start而是start: pnpm prestart docusaurus start, prestart: pnpm examples:clean pnpm examples:build ts-node insertCodeExamples.ts pnpm format也就是说每次启动开发服务器之前都会先完整跑一遍“文档示例预处理流水线”共四步examples:clean用rimraf ../docs/examples/dist删除上一轮编译产物保证示例输出干净examples:build执行ts-node compileExamples.ts把 docs/examples/ 目录下的 TypeScript 示例编译为 JavaScript细节见下节随后用oxfmt格式化ts-node insertCodeExamples.ts将编译好的 TS/JS 双版本示例注入到 MDX 文档的占位符中format对website下的 TS/TSX 文件和docs/做整体格式化。这条流水线保证了文档中展示的代码永远与实际示例文件、以及其编译后的 JavaScript 版本保持一致而不是手工维护两份容易漂移的代码块。示例编译compileExamples.ts 的空白保留机制website/compileExamples.ts 递归遍历 docs/examples/ 目录对每个.ts/.tsx文件调用ts.transpileModule编译为.js/.jsx输出目录由 docs/examples/tsconfig.json 的outDir: dist决定即 docs/examples/dist/。示例的tsconfig.json中还配置了paths映射如reselect: [../../src/index]使示例可以直接从仓库源码解析reselect包展示的是真实实现的用法。该脚本的一个工程细节是“空白保留”whitespace preservationTypeScript 的 transpile 默认会破坏手工排版好的对齐空格例如类型标注前后的列对齐因此脚本在编译前先把连续空格、冒号前空格、空行和同行else等空白信息替换成唯一的/*tag*/占位标记并记录元数据编译后再按标记还原使生成的 JS 代码在视觉排版上尽量贴近源码。这一机制源自gulp-preserve-typescript-whitespace的思路见 website/compileExamples.ts 的注释说明这里改造为基于 ts-node 的实现。示例注入insertCodeExamples.ts 的占位符替换website/insertCodeExamples.ts 定义了注入的核心规则正则insertCodeExamples.ts#L10-L11{/\* START: (.*?) \*/}([\s\S]*?){/\* END: \1 \*/}即文档中形如下面的占位符标记{/* START: basicUsage.ts */} {/* END: basicUsage.ts */}会被替换为一段 Docusaurus 的Tabs/TabItem组件代码包含两个语言页签TypeScript页签展示.ts源文件内容JavaScript页签展示对应.js编译产物内容代码块标题为文件名。脚本会自动递归扫描docs/下所有含占位符的.mdx文件并原地写回若文档尚未引入则还会自动补上import Tabs from theme/Tabs等导入语句。仓库中 website/docs/ 下多篇文档使用了这种占位符例如 website/docs/api/createSelector.mdx、website/docs/api/weakMapMemoize.mdx 与 website/docs/FAQ.mdx。这套机制的实际价值示例代码只维护一份 TS 源文件位于docs/examples/网站自动同时呈现 TypeScript 与 JavaScript 两种可读版本读者看到的代码就是可运行、可检查的真实代码。构建静态站点pnpm buildREADME 给出的构建命令$ pnpm build对应 website/package.json 中的build: docusaurus build产物输出到build/目录可以用任意静态内容托管服务来发布。构建时onBrokenLinks: throw会确保失效链接直接让构建失败这是文档站链接质量的硬校验。部署GitHub Pages 与 Netlify 两条路径README 中描述的部署方式面向 GitHub Pages利用 Docusaurus 内置的 deploy 命令一键构建并推送gh-pages分支# 使用 SSH 推送 $ USE_SSHtrue pnpm deploy # 不使用 SSHHTTP 协议 $ GIT_USERYour GitHub username pnpm deploy这条命令能工作依赖 website/docusaurus.config.ts 中的organizationName: reduxjs与projectName: reselect配置即 README 所指的 “GitHub pages deployment config”。不过从仓库中的实际生产配置看文档站的正式部署走的是 Netlifynetlify.toml 位于仓库根目录关键配置如下base website、publish build即构建上下文为website/、发布产物为build/目录构建命令为pnpm install --frozen-lockfile pnpm build使用冻结 lockfile 保证构建可复现[build.environment]中NODE_VERSION 22注释说明 pnpm 11 需要 Node 22.13并通过NODE_OPTIONS --max_old_space_size4096提高构建内存上限NETLIFY_USE_PNPM trueNetlify 从 lockfile 检测到 pnpmCorepack 则从packageManager字段读取版本号通过netlify-plugin-cache插件缓存node_modules/.cache与.pnpm-store加速后续构建ignore git diff --quiet HEAD^ HEAD -- ./docs/ .使得只有docs/或仓库内容有变化时才触发重新构建。仓库根目录还有CNAME文件用于将域名绑定到https://reselect.js.org这一生产 URL。常用脚本速查除 README 覆盖的start/build/deploy外website/package.json 还暴露了一组 Docusaurus 标准命令均直接透传给docusaurusCLI脚本命令用途startprestart docusaurus start启动开发服务器含示例预处理流水线builddocusaurus build构建静态站点到build/deploydocusaurus deploy构建并部署到 GitHub Pages 的gh-pages分支servedocusaurus serve本地预览构建产物cleardocusaurus clear清除 Docusaurus 缓存swizzledocusaurus swizzle将默认主题组件复制到本地以便定制write-translationsdocusaurus write-translations导出翻译字符串write-heading-idsdocusaurus write-heading-ids生成标题锚点 IDtypechecktsc对站点源码做类型检查配合 website/tsconfig.json小结Reselect 的文档站工程可以概括为三层独立的站点项目website/拥有独立 lockfile 与 pnpm 配置通过根目录docs:*脚本与主库解耦协作可复现的示例流水线pnpm start前自动完成“清理 → 编译 TS 示例 → 注入 MDX 占位符 → 格式化”使文档中的代码示例始终与docs/examples/源码一致并同时提供 TypeScript/JavaScript 双版本双通道部署README 提供了面向 GitHub Pages 的pnpm deploySSH 与 HTTP 两种方式而仓库中 netlify.toml 显示生产环境实际托管在 Netlify 上配合 Node 22、frozen-lockfile 与构建缓存保证部署的可复现性。如果你要查阅文档站呈现的 API 细节侧边栏对应的源文件都位于 website/docs/ 目录如 website/docs/api/createSelector.mdx如果要理解示例代码的原始出处则应查看 docs/examples/ 目录下的 TypeScript 源文件。【免费下载链接】reselectSelector library for Redux项目地址: https://gitcode.com/gh_mirrors/re/reselect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Reselect 文档站工程实践：website/ 目录 Docusaurus 站点的开发、构建与部署全流程
Reselect 文档站工程实践website/ 目录 Docusaurus 站点的开发、构建与部署全流程【免费下载链接】reselectSelector library for Redux项目地址: https://gitcode.com/gh_mirrors/re/reselectReselect 的官方文档站位于website/目录基于 Docusaurus 构建覆盖安装、本地开发、静态构建与生产部署的完整工程链路。本文以 website/README.md 为主线结合package.json脚本、Docusaurus 配置和文档示例注入脚本的真实实现讲清楚这个文档站“如何跑起来、如何构建、如何上线”以及它在启动前自动编译文档代码示例的底层机制。website/ 是一个独立的 pnpm 项目理解这个文档站工程的第一步是明确它和仓库主体的关系仓库根目录 pnpm-workspace.yaml 中明确注明website/是一个独立的 pnpm 项目拥有自己的 lockfile 和自己的pnpm-workspace.yaml并不属于根 workspace 的成员包仓库根 package.json 中提供了转发脚本可以直接在根目录操作文档站docs:start、docs:build、docs:clear、docs:serve它们分别通过pnpm --dir website run start等命令转发到website/目录执行website/package.json 声明了engines.node 18和packageManager: pnpm11.23.0即本地运行文档站需要 Node 18 以上、pnpm 11.x 环境。依赖方面website/package.json 使用docusaurus/core与docusaurus/preset-classic3.10.2 版本、React 19并额外引入了getcanary/docusaurus-theme-search-pagefind主题插件用于全文搜索prism-react-renderer用于代码高亮。README 中提到的pnpm install就是在这个目录下执行安装的是这份独立 lockfile 对应的依赖树。站点核心配置docusaurus.config.ts 与 sidebars.tswebsite/docusaurus.config.ts 定义了站点的身份与行为几个关键点配置项取值作用title/taglineReselect/A memoized selector library for Redux站点标题与副标题也用于首页 hero 区域urlhttps://reselect.js.org生产环境 URLbaseUrl/站点部署在域名根路径下organizationName/projectNamereduxjs/reselectGitHub Pages 部署配置见后文部署章节onBrokenLinksthrow构建时发现失效链接直接报错保证链接质量i18n仅en当前只维护英文文档文档插件classic preset 的docs配置了sidebarPath: ./sidebars.ts、showLastUpdateTime: true、routeBasePath: /文档直接挂在站点根路径以及指向仓库编辑入口的editUrl。站点还通过themes数组加载了 Pagefind 搜索主题并在themeConfig中启用了 Monokai 代码主题prism.theme: require(./monokaiTheme.js)对应 website/monokaiTheme.js。website/sidebars.ts 采用显式定义而非目录自动扫描生成侧边栏组织为四个分组Introductiongetting-started、how-does-reselect-work、v5-summary、APIcreateSelector、createSelectorCreator、createStructuredSelector、development-only-checks以及 lruMemoize、weakMapMemoize 两个 Memoization Functions 子项、Using Reselectbest-practices、common-mistakes、handling-empty-array-results以及 FAQ、external-references、related-projects 三篇独立文档。侧边栏中的docId对应 website/docs/ 目录下的实际文件修改文档结构时需同步维护这份配置。安装与本地开发pnpm start 到底做了什么README 给出的开发流程是两条命令# 安装依赖 $ pnpm install # 启动本地开发服务器自动打开浏览器 $ pnpm startpnpm start会启动 Docusaurus 开发服务器多数改动无需重启即可实时生效。但值得注意的是website/package.json 中start并非直接执行docusaurus start而是start: pnpm prestart docusaurus start, prestart: pnpm examples:clean pnpm examples:build ts-node insertCodeExamples.ts pnpm format也就是说每次启动开发服务器之前都会先完整跑一遍“文档示例预处理流水线”共四步examples:clean用rimraf ../docs/examples/dist删除上一轮编译产物保证示例输出干净examples:build执行ts-node compileExamples.ts把 docs/examples/ 目录下的 TypeScript 示例编译为 JavaScript细节见下节随后用oxfmt格式化ts-node insertCodeExamples.ts将编译好的 TS/JS 双版本示例注入到 MDX 文档的占位符中format对website下的 TS/TSX 文件和docs/做整体格式化。这条流水线保证了文档中展示的代码永远与实际示例文件、以及其编译后的 JavaScript 版本保持一致而不是手工维护两份容易漂移的代码块。示例编译compileExamples.ts 的空白保留机制website/compileExamples.ts 递归遍历 docs/examples/ 目录对每个.ts/.tsx文件调用ts.transpileModule编译为.js/.jsx输出目录由 docs/examples/tsconfig.json 的outDir: dist决定即 docs/examples/dist/。示例的tsconfig.json中还配置了paths映射如reselect: [../../src/index]使示例可以直接从仓库源码解析reselect包展示的是真实实现的用法。该脚本的一个工程细节是“空白保留”whitespace preservationTypeScript 的 transpile 默认会破坏手工排版好的对齐空格例如类型标注前后的列对齐因此脚本在编译前先把连续空格、冒号前空格、空行和同行else等空白信息替换成唯一的/*tag*/占位标记并记录元数据编译后再按标记还原使生成的 JS 代码在视觉排版上尽量贴近源码。这一机制源自gulp-preserve-typescript-whitespace的思路见 website/compileExamples.ts 的注释说明这里改造为基于 ts-node 的实现。示例注入insertCodeExamples.ts 的占位符替换website/insertCodeExamples.ts 定义了注入的核心规则正则insertCodeExamples.ts#L10-L11{/\* START: (.*?) \*/}([\s\S]*?){/\* END: \1 \*/}即文档中形如下面的占位符标记{/* START: basicUsage.ts */} {/* END: basicUsage.ts */}会被替换为一段 Docusaurus 的Tabs/TabItem组件代码包含两个语言页签TypeScript页签展示.ts源文件内容JavaScript页签展示对应.js编译产物内容代码块标题为文件名。脚本会自动递归扫描docs/下所有含占位符的.mdx文件并原地写回若文档尚未引入则还会自动补上import Tabs from theme/Tabs等导入语句。仓库中 website/docs/ 下多篇文档使用了这种占位符例如 website/docs/api/createSelector.mdx、website/docs/api/weakMapMemoize.mdx 与 website/docs/FAQ.mdx。这套机制的实际价值示例代码只维护一份 TS 源文件位于docs/examples/网站自动同时呈现 TypeScript 与 JavaScript 两种可读版本读者看到的代码就是可运行、可检查的真实代码。构建静态站点pnpm buildREADME 给出的构建命令$ pnpm build对应 website/package.json 中的build: docusaurus build产物输出到build/目录可以用任意静态内容托管服务来发布。构建时onBrokenLinks: throw会确保失效链接直接让构建失败这是文档站链接质量的硬校验。部署GitHub Pages 与 Netlify 两条路径README 中描述的部署方式面向 GitHub Pages利用 Docusaurus 内置的 deploy 命令一键构建并推送gh-pages分支# 使用 SSH 推送 $ USE_SSHtrue pnpm deploy # 不使用 SSHHTTP 协议 $ GIT_USERYour GitHub username pnpm deploy这条命令能工作依赖 website/docusaurus.config.ts 中的organizationName: reduxjs与projectName: reselect配置即 README 所指的 “GitHub pages deployment config”。不过从仓库中的实际生产配置看文档站的正式部署走的是 Netlifynetlify.toml 位于仓库根目录关键配置如下base website、publish build即构建上下文为website/、发布产物为build/目录构建命令为pnpm install --frozen-lockfile pnpm build使用冻结 lockfile 保证构建可复现[build.environment]中NODE_VERSION 22注释说明 pnpm 11 需要 Node 22.13并通过NODE_OPTIONS --max_old_space_size4096提高构建内存上限NETLIFY_USE_PNPM trueNetlify 从 lockfile 检测到 pnpmCorepack 则从packageManager字段读取版本号通过netlify-plugin-cache插件缓存node_modules/.cache与.pnpm-store加速后续构建ignore git diff --quiet HEAD^ HEAD -- ./docs/ .使得只有docs/或仓库内容有变化时才触发重新构建。仓库根目录还有CNAME文件用于将域名绑定到https://reselect.js.org这一生产 URL。常用脚本速查除 README 覆盖的start/build/deploy外website/package.json 还暴露了一组 Docusaurus 标准命令均直接透传给docusaurusCLI脚本命令用途startprestart docusaurus start启动开发服务器含示例预处理流水线builddocusaurus build构建静态站点到build/deploydocusaurus deploy构建并部署到 GitHub Pages 的gh-pages分支servedocusaurus serve本地预览构建产物cleardocusaurus clear清除 Docusaurus 缓存swizzledocusaurus swizzle将默认主题组件复制到本地以便定制write-translationsdocusaurus write-translations导出翻译字符串write-heading-idsdocusaurus write-heading-ids生成标题锚点 IDtypechecktsc对站点源码做类型检查配合 website/tsconfig.json小结Reselect 的文档站工程可以概括为三层独立的站点项目website/拥有独立 lockfile 与 pnpm 配置通过根目录docs:*脚本与主库解耦协作可复现的示例流水线pnpm start前自动完成“清理 → 编译 TS 示例 → 注入 MDX 占位符 → 格式化”使文档中的代码示例始终与docs/examples/源码一致并同时提供 TypeScript/JavaScript 双版本双通道部署README 提供了面向 GitHub Pages 的pnpm deploySSH 与 HTTP 两种方式而仓库中 netlify.toml 显示生产环境实际托管在 Netlify 上配合 Node 22、frozen-lockfile 与构建缓存保证部署的可复现性。如果你要查阅文档站呈现的 API 细节侧边栏对应的源文件都位于 website/docs/ 目录如 website/docs/api/createSelector.mdx如果要理解示例代码的原始出处则应查看 docs/examples/ 目录下的 TypeScript 源文件。【免费下载链接】reselectSelector library for Redux项目地址: https://gitcode.com/gh_mirrors/re/reselect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考