Cloudflare Docs 的 TypeScriptExample 组件一份针对 Workers 文档代码块的规范与实践指南【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本篇技术指南以 Cloudflare Docs 仓库的 style-guide-review 技能参考文档.flue/.agents/skills/style-guide-review/reference/components/typescript-example.md为主体结合仓库内 TypeScriptExample.astro 组件源码 及其在文档内容中的真实使用案例系统讲解如何在 Workers 相关 MDX 文档中正确使用TypeScriptExample组件实现一份 TypeScript 源码、自动生成 JS TS 双标签页的单一事实来源写法以及该组件背后基于构建时代码生成的核心原理。读完本文你将掌握该组件的全部 Props、三条硬性规范、完整调用示例与常见误区的规避方法。为什么 Workers 文档需要 TypeScriptExampleCloudflare Workers 的官方文档长期面向两类读者偏好使用wrangler原生 TS 工作流的开发者以及使用 JS 快速上手的开发者。如果每一段示例代码都要手写ts与js两个代码块必然出现两处内容漂移——修改了 TS 却忘记同步 JS是最常见的文档维护事故。TypeScriptExample组件就是为了解决这一痛点而设计的作者只需要编写一段ts代码块组件在文档构建时自动从中剥离类型注解生成等价的 JavaScript并以 JavaScript / TypeScript 两个同步标签页的形式渲染。正因如此MDX 中始终只有一份源码真正做到 single-source单一事实来源。这一设计在组件源码的顶部注释中也有明确说明见 src/components/cf/TypeScriptExample.astro。使用方式与 Props 总览在 MDX 中引入组件后将一段ts代码块作为其唯一子节点即可import { TypeScriptExample } from ~/components; TypeScriptExample filenamesrc/index.ts ts export default { async fetch(req, env): PromiseResponse { return new Response(Hello World); }, } satisfies ExportedHandlerEnv;组件支持的 Props 完整清单如下Prop类型是否必填说明filenamestring可选文件名字符串必须以.ts结尾。JS 标签页会自动显示对应的.js等价文件名omitTabsboolean可选为true时不再渲染 JS/TS 双标签页只渲染单份代码playgroundboolean可选为true时在代码下方追加 Run Worker in Playground 按钮点击可在 Cloudflare Workers Playground 中直接运行codeAstroCode组件的选项可选透传给内部每一个渲染的Code块用于设置collapse等代码展示选项从源码的 Props 声明src/components/cf/TypeScriptExample.astro可以看到omitTabs与playground的默认值均为false。三条核心使用规则参考文档明确了三条必须遵守的规则违反任何一条都会被 style-guide 审查标记为 warning规则一Workers 风格代码必须使用 TypeScriptExample如果文档中出现一段js或ts围栏代码块且其中包含 Workers 风格代码——即存在以下任一特征从cloudflare:workers导入从hono导入从cloudflare/命名空间导入导出default处理器如export default { async fetch(...) {} }则应当使用TypeScriptExample代替裸围栏代码块否则触发 warning。这是为了保证 Workers 示例在文档中展示形式统一且 JS 与 TS 两个版本始终同步。规则二filename 必须以 .ts 结尾filename属性如果未以.ts结尾同样触发 warning。原因很直接组件内部依赖该后缀做文件名换算——JS 标签页的文件标题是通过把.ts替换为.js得到的源码实现见下文。如果传入filenamesrc/index.js之类的值整个换算逻辑就会失效。规则三Code 选项必须通过 code 属性传入collapse等Code组件选项不能直接写在内部围栏代码块的 meta 上而应通过TypeScriptExample的code属性传入。例如TypeScriptExample filenamesrc/index.ts code{{ collapse: true }}这是因为组件会把code展开到内部渲染的每一个Code块上只有经由code属性才能同时作用于 JS 与 TS 两个标签页。源码级原理构建时如何从 TS 生成 JSTypeScriptExample不是简单的客户端选项卡切换其一份 TS 生成双标签页的能力在构建期完成。其核心实现位于 src/components/cf/TypeScriptExample.astro整体流程可以拆解为五个环节1. 槽位内容提取。组件通过Astro.slots.render(default)取到内部的ts代码块原始 HTML再用node-html-parser定位到pre code元素取出其中的源码文本。若槽位中不存在围栏代码块组件会直接抛错Expected a fenced ts code block as the only child。2. 动态日期替换。源码中有一个上游约定代码内出现compatibilityDate: $today时组件会用当前构建日期替换即new Date().toISOString().split(T)[0]避免文档示例中的 compatibility date 随内容陈旧过期。3. TS 转 JS。这一步借助ts-blank-space库将 TypeScript 源码剥离为空白占位的 JS 等价物再用prettier以parser: babel、useTabs: true进行格式化得到干净、可读的 JS 版本。4. 生成文件名与标签页。标签页结构与同步行为由仓库的Tabs/TabItem组件承担且使用syncKey: workersExamples保证页面内多个示例的标签切换保持同步。有filename时JS 标签页标题通过filename.replace(.ts, .js)换算没有filename时TS 标签页直接复用槽位中已经渲染好的 HTML避免重复高亮开销。5. Playground 链接构造可选。当playground为true时组件将生成的 JS 打包成一个 Workers module bundleindex.js作为main_module用lz-string压缩编码为 URI fragment拼出https://workers.cloudflare.com/playground#...链接并通过LinkButton渲染 Run Worker in Playground 按钮。这意味着读者点击按钮即可在 Playground 中直接运行这份自动生成的 JS 代码。组件通过 src/components.ts 的export { default as TypeScriptExample } from ./components/cf/TypeScriptExample.astro对外注册文档 MDX 中即可通过import { TypeScriptExample } from ~/components使用。仓库内的真实使用场景TypeScriptExample在文档内容中已被广泛使用典型的真实示例之一是 src/content/docs/agents/model-context-protocol/apis/handler-api.mdx其中用该组件展示了createLegacyMcpHandler的迁移用法TypeScriptExample filenamesrc/index.ts ts import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { createLegacyMcpHandler } from agents/mcp; function createServer() { return new McpServer({ name: legacy-server, version: 1.0.0 }); } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext) { return createLegacyMcpHandler(createServer())(request, env, ctx); }, } satisfies ExportedHandlerEnv;这段代码同时满足参考文档中的三条规则导出了default处理器符合规则一的必须用组件、filename以.ts结尾规则二、未在内层围栏上悬挂collapse等 Code 选项规则三。类似的用法在src/content/docs/agent-memory/get-started.mdx等大量 Workers 系文档中反复出现是判断代码风格是否合规的最直观对照。编写 TypeScriptExample 代码块时的实践要点结合参考规则与组件实现在文档中编写此类代码块时建议遵循以下要点永远只写 TS 版本JS 由构建器自动生成不要在文档中手工维护两套代码。保留 Workers 特征标识export default { async fetch ... } satisfies ExportedHandlerEnv这类写法既是合法的 Workers 入口也是 style-guide 识别应使用组件的信号。filename 与文件路径保持一致推荐按src/index.ts、src/server.ts这样的真实目录结构命名便于读者与自己的项目结构对应。依赖示例中的日期示例涉及compatibility_date时可直接写compatibilityDate: $today构建时会自动替换为实际构建日期。代码选项统一走code属性需要折叠长代码块时使用code{{ collapse: true }}不要塞进内层围栏。需要单语言展示时用omitTabs当一段代码不需要 JS 版本时设置omitTabs可避免无意义的双标签页。需要一键运行体验时用playground为可独立运行的完整 Worker 示例开启该选项提升读者验证成本低的沉浸体验。审查机制规则如何被强制执行这些规则并不是约定俗成的软建议而是由仓库内置的 style-guide-review 技能在代码审查环节机械执行的硬性检查项。技能说明见 .flue/.agents/skills/style-guide-review/SKILL.md它只针对 PR 中新增的行做精确的模式匹配命中参考文档中的规则即产出warning或suggestion级别的结构化 findings再调用submit_style_guide工具回传。这意味着任何新增的裸 Workers 代码围栏、非法filename后缀或错误放置的 Code 选项都会在合入前被机器化地拦截。该技能的相关规则文件与组件说明一同维护在 reference/components/typescript-example.md与本文所讲解的组件规范完全对应。综上TypeScriptExample组件体现了 Cloudflare Docs 在文档示例单一事实来源上的工程化思路作者只维护一份 TS 源码构建期自动生成 JS 并封装为同步标签页再叠加 Playground 一键运行能力最终由自动化审查保障规范落地——对任何面向多语言开发者的技术文档项目这套组件 构建生成 机械审查的组合都值得借鉴。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 14:51:59 · 阅读 1.2k Cloudflare Docs 的 TypeScriptExample 组件：一份针对 Workers 文档代码块的规范与实践指南
Cloudflare Docs 的 TypeScriptExample 组件一份针对 Workers 文档代码块的规范与实践指南【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本篇技术指南以 Cloudflare Docs 仓库的 style-guide-review 技能参考文档.flue/.agents/skills/style-guide-review/reference/components/typescript-example.md为主体结合仓库内 TypeScriptExample.astro 组件源码 及其在文档内容中的真实使用案例系统讲解如何在 Workers 相关 MDX 文档中正确使用TypeScriptExample组件实现一份 TypeScript 源码、自动生成 JS TS 双标签页的单一事实来源写法以及该组件背后基于构建时代码生成的核心原理。读完本文你将掌握该组件的全部 Props、三条硬性规范、完整调用示例与常见误区的规避方法。为什么 Workers 文档需要 TypeScriptExampleCloudflare Workers 的官方文档长期面向两类读者偏好使用wrangler原生 TS 工作流的开发者以及使用 JS 快速上手的开发者。如果每一段示例代码都要手写ts与js两个代码块必然出现两处内容漂移——修改了 TS 却忘记同步 JS是最常见的文档维护事故。TypeScriptExample组件就是为了解决这一痛点而设计的作者只需要编写一段ts代码块组件在文档构建时自动从中剥离类型注解生成等价的 JavaScript并以 JavaScript / TypeScript 两个同步标签页的形式渲染。正因如此MDX 中始终只有一份源码真正做到 single-source单一事实来源。这一设计在组件源码的顶部注释中也有明确说明见 src/components/cf/TypeScriptExample.astro。使用方式与 Props 总览在 MDX 中引入组件后将一段ts代码块作为其唯一子节点即可import { TypeScriptExample } from ~/components; TypeScriptExample filenamesrc/index.ts ts export default { async fetch(req, env): PromiseResponse { return new Response(Hello World); }, } satisfies ExportedHandlerEnv;组件支持的 Props 完整清单如下Prop类型是否必填说明filenamestring可选文件名字符串必须以.ts结尾。JS 标签页会自动显示对应的.js等价文件名omitTabsboolean可选为true时不再渲染 JS/TS 双标签页只渲染单份代码playgroundboolean可选为true时在代码下方追加 Run Worker in Playground 按钮点击可在 Cloudflare Workers Playground 中直接运行codeAstroCode组件的选项可选透传给内部每一个渲染的Code块用于设置collapse等代码展示选项从源码的 Props 声明src/components/cf/TypeScriptExample.astro可以看到omitTabs与playground的默认值均为false。三条核心使用规则参考文档明确了三条必须遵守的规则违反任何一条都会被 style-guide 审查标记为 warning规则一Workers 风格代码必须使用 TypeScriptExample如果文档中出现一段js或ts围栏代码块且其中包含 Workers 风格代码——即存在以下任一特征从cloudflare:workers导入从hono导入从cloudflare/命名空间导入导出default处理器如export default { async fetch(...) {} }则应当使用TypeScriptExample代替裸围栏代码块否则触发 warning。这是为了保证 Workers 示例在文档中展示形式统一且 JS 与 TS 两个版本始终同步。规则二filename 必须以 .ts 结尾filename属性如果未以.ts结尾同样触发 warning。原因很直接组件内部依赖该后缀做文件名换算——JS 标签页的文件标题是通过把.ts替换为.js得到的源码实现见下文。如果传入filenamesrc/index.js之类的值整个换算逻辑就会失效。规则三Code 选项必须通过 code 属性传入collapse等Code组件选项不能直接写在内部围栏代码块的 meta 上而应通过TypeScriptExample的code属性传入。例如TypeScriptExample filenamesrc/index.ts code{{ collapse: true }}这是因为组件会把code展开到内部渲染的每一个Code块上只有经由code属性才能同时作用于 JS 与 TS 两个标签页。源码级原理构建时如何从 TS 生成 JSTypeScriptExample不是简单的客户端选项卡切换其一份 TS 生成双标签页的能力在构建期完成。其核心实现位于 src/components/cf/TypeScriptExample.astro整体流程可以拆解为五个环节1. 槽位内容提取。组件通过Astro.slots.render(default)取到内部的ts代码块原始 HTML再用node-html-parser定位到pre code元素取出其中的源码文本。若槽位中不存在围栏代码块组件会直接抛错Expected a fenced ts code block as the only child。2. 动态日期替换。源码中有一个上游约定代码内出现compatibilityDate: $today时组件会用当前构建日期替换即new Date().toISOString().split(T)[0]避免文档示例中的 compatibility date 随内容陈旧过期。3. TS 转 JS。这一步借助ts-blank-space库将 TypeScript 源码剥离为空白占位的 JS 等价物再用prettier以parser: babel、useTabs: true进行格式化得到干净、可读的 JS 版本。4. 生成文件名与标签页。标签页结构与同步行为由仓库的Tabs/TabItem组件承担且使用syncKey: workersExamples保证页面内多个示例的标签切换保持同步。有filename时JS 标签页标题通过filename.replace(.ts, .js)换算没有filename时TS 标签页直接复用槽位中已经渲染好的 HTML避免重复高亮开销。5. Playground 链接构造可选。当playground为true时组件将生成的 JS 打包成一个 Workers module bundleindex.js作为main_module用lz-string压缩编码为 URI fragment拼出https://workers.cloudflare.com/playground#...链接并通过LinkButton渲染 Run Worker in Playground 按钮。这意味着读者点击按钮即可在 Playground 中直接运行这份自动生成的 JS 代码。组件通过 src/components.ts 的export { default as TypeScriptExample } from ./components/cf/TypeScriptExample.astro对外注册文档 MDX 中即可通过import { TypeScriptExample } from ~/components使用。仓库内的真实使用场景TypeScriptExample在文档内容中已被广泛使用典型的真实示例之一是 src/content/docs/agents/model-context-protocol/apis/handler-api.mdx其中用该组件展示了createLegacyMcpHandler的迁移用法TypeScriptExample filenamesrc/index.ts ts import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { createLegacyMcpHandler } from agents/mcp; function createServer() { return new McpServer({ name: legacy-server, version: 1.0.0 }); } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext) { return createLegacyMcpHandler(createServer())(request, env, ctx); }, } satisfies ExportedHandlerEnv;这段代码同时满足参考文档中的三条规则导出了default处理器符合规则一的必须用组件、filename以.ts结尾规则二、未在内层围栏上悬挂collapse等 Code 选项规则三。类似的用法在src/content/docs/agent-memory/get-started.mdx等大量 Workers 系文档中反复出现是判断代码风格是否合规的最直观对照。编写 TypeScriptExample 代码块时的实践要点结合参考规则与组件实现在文档中编写此类代码块时建议遵循以下要点永远只写 TS 版本JS 由构建器自动生成不要在文档中手工维护两套代码。保留 Workers 特征标识export default { async fetch ... } satisfies ExportedHandlerEnv这类写法既是合法的 Workers 入口也是 style-guide 识别应使用组件的信号。filename 与文件路径保持一致推荐按src/index.ts、src/server.ts这样的真实目录结构命名便于读者与自己的项目结构对应。依赖示例中的日期示例涉及compatibility_date时可直接写compatibilityDate: $today构建时会自动替换为实际构建日期。代码选项统一走code属性需要折叠长代码块时使用code{{ collapse: true }}不要塞进内层围栏。需要单语言展示时用omitTabs当一段代码不需要 JS 版本时设置omitTabs可避免无意义的双标签页。需要一键运行体验时用playground为可独立运行的完整 Worker 示例开启该选项提升读者验证成本低的沉浸体验。审查机制规则如何被强制执行这些规则并不是约定俗成的软建议而是由仓库内置的 style-guide-review 技能在代码审查环节机械执行的硬性检查项。技能说明见 .flue/.agents/skills/style-guide-review/SKILL.md它只针对 PR 中新增的行做精确的模式匹配命中参考文档中的规则即产出warning或suggestion级别的结构化 findings再调用submit_style_guide工具回传。这意味着任何新增的裸 Workers 代码围栏、非法filename后缀或错误放置的 Code 选项都会在合入前被机器化地拦截。该技能的相关规则文件与组件说明一同维护在 reference/components/typescript-example.md与本文所讲解的组件规范完全对应。综上TypeScriptExample组件体现了 Cloudflare Docs 在文档示例单一事实来源上的工程化思路作者只维护一份 TS 源码构建期自动生成 JS 并封装为同步标签页再叠加 Playground 一键运行能力最终由自动化审查保障规范落地——对任何面向多语言开发者的技术文档项目这套组件 构建生成 机械审查的组合都值得借鉴。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考