tinacms/astro 全解析TinaCMS 与 Astro 的一体化视觉编辑集成指南【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacmstinacms/astro是 TinaCMS 官方为 Astro 框架提供的一站式集成包它在一次安装中同时打包了富文本渲染器TinaMarkdown、框架无关的 Bridge 运行时与tina()集成插件让 Astro 项目无需引入 React 即可获得完整的可视化编辑能力。本文基于仓库中 packages/tinacms/astro/CHANGELOG.md 的演进记录结合 包源码 与 官方入门指南系统讲解该包从 0.2.0 到 0.7.0 的核心能力、子路径 API、静态站点编辑方案、依赖管理修复与 Astro 5/6/7 兼容策略读完即可在现有 Astro 应用中接入 TinaCMS 视觉编辑。一、从零到一0.2.0 版本的新包发布tinacms/astro在 0.2.0 版本正式诞生定位为使用 TinaCMS 与 Astro 的一站式集成。其设计核心是富文本渲染器与框架无关的 Bridge 被捆绑在一次安装中tinacms/bridge仍然可以独立发布给非 Astro 前端如 Hugo、纯 HTML但 Astro 项目只需要tinacms/astro一个包。1.1 安装与 peer 依赖pnpm add tinacms/astropeer 依赖要求astro 5.0.0包内部使用 Astro 的 Container API 渲染岛屿islands并向消费方 Astro 管线直接分发.astro源文件由其编译。到 0.7.0 时package.json 中的 peer 依赖已扩展为astro: ^5.0.0 || ^6.0.0 || ^7.0.0同时支持三个大版本。运行时依赖仅tinacms/bridge以workspace:^声明发布时转为 caret 范围。1.2 完整的子路径导出清单CHANGELOG 0.2.0 记录了完整的导出面当前 package.json 的exports字段与其一一对应子路径提供内容tinacms/astrorequestWithMetadata、tinaField、QueryResult及富文本类型tinacms/astro/TinaMarkdown.astroTinaMarkdown content components /富文本渲染器通过子路径导入Astro 的 check 才能看到真正的.astro组件tinacms/astro/integrationtina()集成——自动接线 middleware 与 bridge 路由让requestWithMetadata()无需手动传递Astro.request或编写接线组件tinacms/astro/TinaIsland.astroTinaIsland name wrapper params /可编辑区域的标记包装器tinacms/astro/typesTinaRichTextContent、CustomComponentsMap、TinaRichTextNode、MdxElement、TextElement等tinacms/astro/sanitize面向 CMS 提供 URL 的sanitizeHref/sanitizeImageSrctinacms/astro/bridgeinit、refreshForms以及tinacms/bridge的其余能力tinacms/astro/tina-field生成data-tina-field标记的tinaField()辅助函数tinacms/astro/is-edit-modeisEditMode(request)—— 服务端 admin iframe 检测tinacms/astro/experimentalexperimental_createIslandRoute()—— 动态/tina-island/[name]端点的可选辅助函数1.3 一个组件双条件导出的实现细节值得注意的实现细节在 src/index.tstinacms/astro的.子路径通过astro导出条件直接指向src/TinaMarkdown.astroAstro 消费方拿到的是真实组件而走types/default条件的工具TypeScript 类型检查、纯 Node ESM 解析拿到的是占位默认导出——它在被调用时会抛出带清晰指引的错误throw new Error( [tinacms/astro] TinaMarkdown must be loaded through Astros pipeline. Add tina() from tinacms/astro/integration to your astro.config integrations, or import directly from tinacms/astro/TinaMarkdown.astro. );该占位符的类型被构造成AstroComponentFactory与带 props 签名的交叉类型从而让 Astro 语言服务器既把它识别为可渲染组件又能在调用点给出 props 补全与类型报错。这正是入门指南中反复强调必须从/TinaMarkdown.astro子路径导入的根本原因。二、渲染器与数据流TinaMarkdown requestWithMetadata2.1 TinaMarkdown 渲染器src/TinaMarkdown.astro 是 React 版TinaMarkdown位于packages/tinacms/src/rich-text/index.tsx的 Astro 移植遍历 Tina 富文本的 Plate AST 并输出 Astro 标记通过递归调用自身处理嵌套富文本。与 React 渲染器保持相同 API同样的contentprop、同样的componentsmap 形状输出纯 HTML页面树中不含任何 React自定义 MDX 组件按名称注册mdxJsxFlowElement/mdxJsxTextElement默认标签p、h1~h6、ul、ol、li、blockquote等可通过在同一 map 上注册同名键覆盖。典型用法来自 CHANGELOG 0.2.0 的示例--- import TinaMarkdown from tinacms/astro/TinaMarkdown.astro; import { requestWithMetadata, tinaField } from tinacms/astro; import client from ../tina/__generated__/client; import { customComponents } from ../components/markdown; const post await requestWithMetadata( client.queries.post({ relativePath: hello.md }), ); --- div>script is:inline typemodule define:vars{{ adminOrigin }} if (window.self ! window.top !window.__tinaBootstrap) { window.__tinaBootstrap 1; const { init, refreshForms } await import(/admin/bridge.js); init(adminOrigin ? { adminOrigin } : undefined); document.addEventListener(astro:page-load, refreshForms); } /scriptwindow.__tinaBootstrap标志用于在页面存在多个TinaIsland时去重避免重复初始化。4.3 动态 island 端点src/island-route.ts 中的experimental_createIslandRoute(islands)构建在 Astro 的experimental_AstroContainer之上该 API 本身被 Astro 标记为不稳定experimental子路径同样继承此警示任何 minor/patch 都可能变更。IslandConfig的四个字段字段说明fetch(request, params)解析组件所需数据可忽略搜索参数component渲染数据的 Astro 组件AstroComponentFactorywrapperbridge 要替换的外层元素——必须与页面侧 wrapper 一致propsFromData(data, params)把抓取的数据 URL 参数映射为组件 props该端点为每个 island 用AstroContainer.renderToString渲染 HTML当请求携带PRIME_HEADER时在区域 HTML 之前附带渲染表单 payload div。安全性通过rejectIfUnsafe三重校验仅接受 POST、Content-Type 必须包含 preview 类型、sec-fetch-site为 cross-site 时拒绝——生产流量无法同时满足这三个信号。4.4 静态站点编辑的完整条件按 GETTING_STARTED.md 的 Static-site editing 章节静态模式可用需满足每个可编辑区域用已注册的TinaIsland包裹区域重渲染与 bridge 引导都依赖它页面主区域标记primary静态页上 bridge 无法自行判断哪个 island 是页面否则编辑器会落到 Referenced Files每页至多一个src/pages/tina-island/[name].ts保持export const prerender false仍需 SSR 适配器只是output保持static或仅对需要服务端渲染的路由单独设prerender false。权衡使用TinaIsland的页面会在生产 HTML 中多出一行内联引导脚本不再与无 Tina 应用逐字节一致未使用TinaIsland的页面不受影响。五、开发体验修复dev 内容失效0.5.1与 Cloudflare 支持0.4.15.1 新文档不再 4040.5.1 修复了一个典型痛点Astro 在 dev 下会缓存getStaticPaths()结果而通过 Tina GraphQL 客户端查询内容既不属于模块图也不属于内容层集合因此 admin 新建内容后新页面会持续 404直到手动重启 dev server。integration.ts 的devContentInvalidationPlugin方案从生成的 schema 读取集合内容根目录精确追踪 collectionpath指向的任何位置当 schema 不可读时回退到路径启发式markdown 任意位置均计数结构化数据仅在content/目录内计数避免误触发package.json/tsconfig写入监听 Vite watcher 的add/unlink事件用 50ms 定时器合并多次保存触发的连续事件向ssr.hot发送astro:content-changed信号并触发client.hot全量 reload仅限 Astro 6把astro:content-changed转为路由缓存清空的监听器从 Astro 6 起才存在0.5.1 只动 Astro 6Astro 5 保持原状集成在 dev 下对 Astro 5 打印警告。局限Vite 只监听 Astro 项目根目录内的文件localContentPath解析到项目外的内容不会自动刷新路由缓存但tinacms dev自身的 watcher 仍会索引行为与修复前一致。5.2 Cloudflare Workers 适配0.4.1 让实验性 island 路由在astrojs/cloudflare下可用workerd 中打包后的import.meta.url不是合法绝对 URLAstro 的 Container API 在构建 manifest 时无条件执行new URL(import.meta.url)而抛错。修复方式是仅在服务端 bundle 注入占位 URL并新增cloudflareWorkers选项强制开/关省略时检测到astrojs/cloudflare自动启用。六、依赖管理修复workspace 范围声明0.6.10.6.1 修复了一个影响安装体积与解析冲突的工程问题内部依赖此前声明为workspace:*pnpm 发布时会展开为精确版本如tinacms: 3.10.0。精确固定无法与消费方已安装版本去重npm 会嵌套第二份、第三份完整的tinacms及其依赖树。CHANGELOG 给出的实测数据一个标准 Astro TinaCMS 博客产生了3 份tinacms、3 份mermaid186 MB、5 份date-fns151 MB、4 份typescript88 MB合计约 320 MB 重复。同样的展开也作用于peerDependenciesnext-tinacms-cloudinary、tinacms-authjs等包把tinacms: 3.10.0发布为 peer要求消费方恰好安装该版本否则触发ERESOLVE冲突且每次tinacms发版都强制重发所有依赖方。改为workspace:^后发布为 caret 范围^3.10.0可正常去重并让onlyUpdatePeerDependentsWhenOutOfRange生效。当前 package.json 中的tinacms/bridge: workspace:^正是该修复的落地形态。七、版本能力总览版本核心变更0.2.0新包发布tinacms/astro一次性提供渲染器 bridge 集成完整子路径导出peerastro 50.3.0静态站点视觉编辑TinaIsland/tina-island/[name]primingbridge 改静态资源tinaAdminDevRedirect插件0.4.0官方支持 Astro 6peer 变为^5.0.0 \|\| ^6.0.0测试套件与examples/astro/visual-editing升到 Astro 60.4.1astrojs/cloudflare适配器兼容workerdimport.meta.url占位新增cloudflareWorkers选项0.5.0tinamarkdown 新增 Astro 表格0.5.1Astro 6 dev 下内容写入/删除自动重跑getStaticPaths新条目不再 404修复媒体上传/删除路径越界 mediaRoot 的问题0.6.0官方支持 Astro 7peer 扩展为^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0examples/astro/kitchen-sink因 Tailwind PostCSS 迁移需要暂留 Astro 60.6.1内部依赖改为范围声明workspace:^消除约 320 MB 依赖重复与 peer 精确版本冲突0.7.0表格语义化markdown 表格首行渲染为thead/th破坏性样式变更八、在仓库中继续深入完整的逐步接入教程安装、tinacms init、integration 接线、island 注册、TypeScript 配置与故障排查表packages/tinacms/astro/GETTING_STARTED.md参考实现应用与 React kitchen-sink 同 schema、纯 Astro 渲染examples/astro/visual-editing集成源码生命周期钩子与三个 Vite 插件packages/tinacms/astro/src/integration.ts数据流与编辑模式注入packages/tinacms/astro/src/data.ts、packages/tinacms/astro/src/middleware.ts静态岛屿机制packages/tinacms/astro/src/TinaIsland.astro、packages/tinacms/astro/src/island-route.ts底层 vanilla-JS bridgeHugo、纯 HTML 等非 React 前端也可用packages/tinacms/bridgetinacms/astro的演进路径清晰体现了 TinaCMS 的工程取舍用.astro源文件直供消费方管线换取零 React 依赖的纯净输出用 AsyncLocalStorage 贯穿请求上下文让表单收集对业务代码透明用静态资源 按需端点让静态站点同样获得可视化编辑。对 Astro 开发者而言接入成本已被压缩到一个tina()调用 每区域一行TinaIsland而本包源码正是理解这套机制的最佳教材。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 @tinacms/astro 全解析：TinaCMS 与 Astro 的一体化视觉编辑集成指南
tinacms/astro 全解析TinaCMS 与 Astro 的一体化视觉编辑集成指南【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacmstinacms/astro是 TinaCMS 官方为 Astro 框架提供的一站式集成包它在一次安装中同时打包了富文本渲染器TinaMarkdown、框架无关的 Bridge 运行时与tina()集成插件让 Astro 项目无需引入 React 即可获得完整的可视化编辑能力。本文基于仓库中 packages/tinacms/astro/CHANGELOG.md 的演进记录结合 包源码 与 官方入门指南系统讲解该包从 0.2.0 到 0.7.0 的核心能力、子路径 API、静态站点编辑方案、依赖管理修复与 Astro 5/6/7 兼容策略读完即可在现有 Astro 应用中接入 TinaCMS 视觉编辑。一、从零到一0.2.0 版本的新包发布tinacms/astro在 0.2.0 版本正式诞生定位为使用 TinaCMS 与 Astro 的一站式集成。其设计核心是富文本渲染器与框架无关的 Bridge 被捆绑在一次安装中tinacms/bridge仍然可以独立发布给非 Astro 前端如 Hugo、纯 HTML但 Astro 项目只需要tinacms/astro一个包。1.1 安装与 peer 依赖pnpm add tinacms/astropeer 依赖要求astro 5.0.0包内部使用 Astro 的 Container API 渲染岛屿islands并向消费方 Astro 管线直接分发.astro源文件由其编译。到 0.7.0 时package.json 中的 peer 依赖已扩展为astro: ^5.0.0 || ^6.0.0 || ^7.0.0同时支持三个大版本。运行时依赖仅tinacms/bridge以workspace:^声明发布时转为 caret 范围。1.2 完整的子路径导出清单CHANGELOG 0.2.0 记录了完整的导出面当前 package.json 的exports字段与其一一对应子路径提供内容tinacms/astrorequestWithMetadata、tinaField、QueryResult及富文本类型tinacms/astro/TinaMarkdown.astroTinaMarkdown content components /富文本渲染器通过子路径导入Astro 的 check 才能看到真正的.astro组件tinacms/astro/integrationtina()集成——自动接线 middleware 与 bridge 路由让requestWithMetadata()无需手动传递Astro.request或编写接线组件tinacms/astro/TinaIsland.astroTinaIsland name wrapper params /可编辑区域的标记包装器tinacms/astro/typesTinaRichTextContent、CustomComponentsMap、TinaRichTextNode、MdxElement、TextElement等tinacms/astro/sanitize面向 CMS 提供 URL 的sanitizeHref/sanitizeImageSrctinacms/astro/bridgeinit、refreshForms以及tinacms/bridge的其余能力tinacms/astro/tina-field生成data-tina-field标记的tinaField()辅助函数tinacms/astro/is-edit-modeisEditMode(request)—— 服务端 admin iframe 检测tinacms/astro/experimentalexperimental_createIslandRoute()—— 动态/tina-island/[name]端点的可选辅助函数1.3 一个组件双条件导出的实现细节值得注意的实现细节在 src/index.tstinacms/astro的.子路径通过astro导出条件直接指向src/TinaMarkdown.astroAstro 消费方拿到的是真实组件而走types/default条件的工具TypeScript 类型检查、纯 Node ESM 解析拿到的是占位默认导出——它在被调用时会抛出带清晰指引的错误throw new Error( [tinacms/astro] TinaMarkdown must be loaded through Astros pipeline. Add tina() from tinacms/astro/integration to your astro.config integrations, or import directly from tinacms/astro/TinaMarkdown.astro. );该占位符的类型被构造成AstroComponentFactory与带 props 签名的交叉类型从而让 Astro 语言服务器既把它识别为可渲染组件又能在调用点给出 props 补全与类型报错。这正是入门指南中反复强调必须从/TinaMarkdown.astro子路径导入的根本原因。二、渲染器与数据流TinaMarkdown requestWithMetadata2.1 TinaMarkdown 渲染器src/TinaMarkdown.astro 是 React 版TinaMarkdown位于packages/tinacms/src/rich-text/index.tsx的 Astro 移植遍历 Tina 富文本的 Plate AST 并输出 Astro 标记通过递归调用自身处理嵌套富文本。与 React 渲染器保持相同 API同样的contentprop、同样的componentsmap 形状输出纯 HTML页面树中不含任何 React自定义 MDX 组件按名称注册mdxJsxFlowElement/mdxJsxTextElement默认标签p、h1~h6、ul、ol、li、blockquote等可通过在同一 map 上注册同名键覆盖。典型用法来自 CHANGELOG 0.2.0 的示例--- import TinaMarkdown from tinacms/astro/TinaMarkdown.astro; import { requestWithMetadata, tinaField } from tinacms/astro; import client from ../tina/__generated__/client; import { customComponents } from ../components/markdown; const post await requestWithMetadata( client.queries.post({ relativePath: hello.md }), ); --- div>script is:inline typemodule define:vars{{ adminOrigin }} if (window.self ! window.top !window.__tinaBootstrap) { window.__tinaBootstrap 1; const { init, refreshForms } await import(/admin/bridge.js); init(adminOrigin ? { adminOrigin } : undefined); document.addEventListener(astro:page-load, refreshForms); } /scriptwindow.__tinaBootstrap标志用于在页面存在多个TinaIsland时去重避免重复初始化。4.3 动态 island 端点src/island-route.ts 中的experimental_createIslandRoute(islands)构建在 Astro 的experimental_AstroContainer之上该 API 本身被 Astro 标记为不稳定experimental子路径同样继承此警示任何 minor/patch 都可能变更。IslandConfig的四个字段字段说明fetch(request, params)解析组件所需数据可忽略搜索参数component渲染数据的 Astro 组件AstroComponentFactorywrapperbridge 要替换的外层元素——必须与页面侧 wrapper 一致propsFromData(data, params)把抓取的数据 URL 参数映射为组件 props该端点为每个 island 用AstroContainer.renderToString渲染 HTML当请求携带PRIME_HEADER时在区域 HTML 之前附带渲染表单 payload div。安全性通过rejectIfUnsafe三重校验仅接受 POST、Content-Type 必须包含 preview 类型、sec-fetch-site为 cross-site 时拒绝——生产流量无法同时满足这三个信号。4.4 静态站点编辑的完整条件按 GETTING_STARTED.md 的 Static-site editing 章节静态模式可用需满足每个可编辑区域用已注册的TinaIsland包裹区域重渲染与 bridge 引导都依赖它页面主区域标记primary静态页上 bridge 无法自行判断哪个 island 是页面否则编辑器会落到 Referenced Files每页至多一个src/pages/tina-island/[name].ts保持export const prerender false仍需 SSR 适配器只是output保持static或仅对需要服务端渲染的路由单独设prerender false。权衡使用TinaIsland的页面会在生产 HTML 中多出一行内联引导脚本不再与无 Tina 应用逐字节一致未使用TinaIsland的页面不受影响。五、开发体验修复dev 内容失效0.5.1与 Cloudflare 支持0.4.15.1 新文档不再 4040.5.1 修复了一个典型痛点Astro 在 dev 下会缓存getStaticPaths()结果而通过 Tina GraphQL 客户端查询内容既不属于模块图也不属于内容层集合因此 admin 新建内容后新页面会持续 404直到手动重启 dev server。integration.ts 的devContentInvalidationPlugin方案从生成的 schema 读取集合内容根目录精确追踪 collectionpath指向的任何位置当 schema 不可读时回退到路径启发式markdown 任意位置均计数结构化数据仅在content/目录内计数避免误触发package.json/tsconfig写入监听 Vite watcher 的add/unlink事件用 50ms 定时器合并多次保存触发的连续事件向ssr.hot发送astro:content-changed信号并触发client.hot全量 reload仅限 Astro 6把astro:content-changed转为路由缓存清空的监听器从 Astro 6 起才存在0.5.1 只动 Astro 6Astro 5 保持原状集成在 dev 下对 Astro 5 打印警告。局限Vite 只监听 Astro 项目根目录内的文件localContentPath解析到项目外的内容不会自动刷新路由缓存但tinacms dev自身的 watcher 仍会索引行为与修复前一致。5.2 Cloudflare Workers 适配0.4.1 让实验性 island 路由在astrojs/cloudflare下可用workerd 中打包后的import.meta.url不是合法绝对 URLAstro 的 Container API 在构建 manifest 时无条件执行new URL(import.meta.url)而抛错。修复方式是仅在服务端 bundle 注入占位 URL并新增cloudflareWorkers选项强制开/关省略时检测到astrojs/cloudflare自动启用。六、依赖管理修复workspace 范围声明0.6.10.6.1 修复了一个影响安装体积与解析冲突的工程问题内部依赖此前声明为workspace:*pnpm 发布时会展开为精确版本如tinacms: 3.10.0。精确固定无法与消费方已安装版本去重npm 会嵌套第二份、第三份完整的tinacms及其依赖树。CHANGELOG 给出的实测数据一个标准 Astro TinaCMS 博客产生了3 份tinacms、3 份mermaid186 MB、5 份date-fns151 MB、4 份typescript88 MB合计约 320 MB 重复。同样的展开也作用于peerDependenciesnext-tinacms-cloudinary、tinacms-authjs等包把tinacms: 3.10.0发布为 peer要求消费方恰好安装该版本否则触发ERESOLVE冲突且每次tinacms发版都强制重发所有依赖方。改为workspace:^后发布为 caret 范围^3.10.0可正常去重并让onlyUpdatePeerDependentsWhenOutOfRange生效。当前 package.json 中的tinacms/bridge: workspace:^正是该修复的落地形态。七、版本能力总览版本核心变更0.2.0新包发布tinacms/astro一次性提供渲染器 bridge 集成完整子路径导出peerastro 50.3.0静态站点视觉编辑TinaIsland/tina-island/[name]primingbridge 改静态资源tinaAdminDevRedirect插件0.4.0官方支持 Astro 6peer 变为^5.0.0 \|\| ^6.0.0测试套件与examples/astro/visual-editing升到 Astro 60.4.1astrojs/cloudflare适配器兼容workerdimport.meta.url占位新增cloudflareWorkers选项0.5.0tinamarkdown 新增 Astro 表格0.5.1Astro 6 dev 下内容写入/删除自动重跑getStaticPaths新条目不再 404修复媒体上传/删除路径越界 mediaRoot 的问题0.6.0官方支持 Astro 7peer 扩展为^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0examples/astro/kitchen-sink因 Tailwind PostCSS 迁移需要暂留 Astro 60.6.1内部依赖改为范围声明workspace:^消除约 320 MB 依赖重复与 peer 精确版本冲突0.7.0表格语义化markdown 表格首行渲染为thead/th破坏性样式变更八、在仓库中继续深入完整的逐步接入教程安装、tinacms init、integration 接线、island 注册、TypeScript 配置与故障排查表packages/tinacms/astro/GETTING_STARTED.md参考实现应用与 React kitchen-sink 同 schema、纯 Astro 渲染examples/astro/visual-editing集成源码生命周期钩子与三个 Vite 插件packages/tinacms/astro/src/integration.ts数据流与编辑模式注入packages/tinacms/astro/src/data.ts、packages/tinacms/astro/src/middleware.ts静态岛屿机制packages/tinacms/astro/src/TinaIsland.astro、packages/tinacms/astro/src/island-route.ts底层 vanilla-JS bridgeHugo、纯 HTML 等非 React 前端也可用packages/tinacms/bridgetinacms/astro的演进路径清晰体现了 TinaCMS 的工程取舍用.astro源文件直供消费方管线换取零 React 依赖的纯净输出用 AsyncLocalStorage 贯穿请求上下文让表单收集对业务代码透明用静态资源 按需端点让静态站点同样获得可视化编辑。对 Astro 开发者而言接入成本已被压缩到一个tina()调用 每区域一行TinaIsland而本包源码正是理解这套机制的最佳教材。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考