GraphiQL 如何从 UMD 构建迁移到 ESM-based CDN 用法？

GraphiQL 如何从 UMD 构建迁移到 ESM-based CDN 用法【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql如果你是通过 CDN 的script标签在单页 HTML 里加载 GraphiQL那么 4.0.0 的index.umd.jsUMD 构建已经处于废弃状态而在 5.0.0 中 UMD 构建直接被移除。这篇文章给出从旧 UMD CDN 写法切换到官方 ESM-based CDN 用法基于 esm.sh、5.0.0 迁移指南 和 CDN 示例。迁移前先确认你现在用的是哪条 CDN 路径4.0.0 起 UMD 路径已经变更旧路径和新路径对应关系如下引自 4.0.0 迁移指南-https://unpkg.com/graphiql/graphiql.js -https://unpkg.com/graphiql/graphiql.min.js https://unpkg.com/graphiql/dist/index.umd.js // ⚠️ deprecated -https://unpkg.com/graphiql/graphiql.css -https://unpkg.com/graphiql/graphiql.min.css https://unpkg.com/graphiql/dist/style.css如果页面里还有上面标的dist/index.umd.js它只是带废弃标记的新 UMD 路径并不是最终方案。版本层面的两个关键事实GraphiQL 4.xindex.umd.js被标记为 deprecated官方要求切换到 ESM CDN 示例GraphiQL 5.0.0 起UMD 构建已移除graphiql、graphiql/plugin-code-exporter、graphiql/plugin-explorer均如此迁移指南原文为 ⚠️ UMD build is removed. Switch to the ESM CDN example.。此外 4.0.0 起包整体变为ESM only不再有 CommonJS 构建输出。同一份迁移指南还列出了几个随 UMD 时代一起失效的写法如果你的代码里有它们需要一并处理// 默认导出被移除 -import GraphiQL from graphiql import { GraphiQL } from graphiql // 样式导入路径变化 -import graphiql/graphiql.css import graphiql/style.css工具类库react、react-dom、graphql是graphiql的 peer 依赖当前 packages/graphiql/package.json 声明的范围为react/react-dom:^18 || ^19graphql:^15.5.0 || ^16.0.0 || ^17.0.0。4.0.0 起已不再支持 React 16/17。目标形态ESM-based CDN 的完整 HTML 结构官方推荐做法是单个 HTML 文件 importmap script typemodule参考文件为 examples/graphiql-cdn/index.html。整个页面由四部分组成两个样式表linkGraphiQL 与 Explorer 插件各自一份 CSS一个script typeimportmap把所有 npm 包映射到 esm.sh 上的带版本号的 ESM URL并附带integrity值一段script typemodule负责创建 fetcher、组装插件并渲染GraphiQLbody 里唯一的挂载节点div idgraphiql。完整示例引自 examples/graphiql-cdn/index.html版本已固定在 5.4.0!doctype html html langen head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleGraphiQL 5 with React 19 and GraphiQL Explorer/title style body { margin: 0; } #graphiql { height: 100dvh; } .loading { height: 100%; display: flex; align-items: center; justify-content: center; font-size: 4rem; } /style link relstylesheet hrefhttps://esm.sh/graphiql5.4.0/dist/style.css integritysha384-TFpQQKp325U5sd3PddH4cS0KOB3Gz/aqdEe12Mqkkq3wm2MGcDhRX5WhWfo8akh crossoriginanonymous / link relstylesheet hrefhttps://esm.sh/graphiql/plugin-explorer5.1.5/dist/style.css integritysha384-vTFGj0krVqwFXLB7kq/VHR0/j2cCT/B63rge2mULaqnib2OX7DVLUVksTlqvMab crossoriginanonymous / !-- * Note: * The ?standalone flag bundles the module along with all of its dependencies, excluding peerDependencies, into a single JavaScript file. * emotion/is-prop-valid is a shim to remove the console error module emotion /is-prop-valid not found. Upstream issue: https://github.com/motiondivision/motion/issues/3126 -- script typeimportmap { imports: { react: https://esm.sh/react19.2.8, react/: https://esm.sh/react19.2.8/, react-dom: https://esm.sh/react-dom19.2.8, react-dom/: https://esm.sh/react-dom19.2.8/, graphiql: https://esm.sh/graphiql5.4.0?standaloneexternalreact,react-dom,graphiql/react,graphql, graphiql/: https://esm.sh/graphiql5.4.0/, graphiql/plugin-explorer: https://esm.sh/graphiql/plugin-explorer5.1.5?standaloneexternalreact,graphiql/react,graphql, graphiql/react: https://esm.sh/graphiql/react0.39.0?standaloneexternalreact,react-dom,graphql,graphiql/toolkit,emotion/is-prop-valid, graphiql/toolkit: https://esm.sh/graphiql/toolkit0.12.1?standaloneexternalgraphql, graphql: https://esm.sh/graphql17.0.2, emotion/is-prop-valid: data:text/javascript, }, integrity: { https://esm.sh/react19.2.8: sha384-ZLbEMZxxxJSWKr0slZZsXGR6UNzfnEk4qYI9PLH9QSxvWWQjs3UgkzrGuo33roA, https://esm.sh/react-dom19.2.8: sha384-jssD0f2tUCDrNPAwM/2fFwybg7wF0K9oVfFE0a7r0n7wb2UVP4/uYyWIZKGxG6L, https://esm.sh/graphiql5.4.0: sha384-moUMjxK/ZmHQE08otOtzYT/Zke32MqPb9l0uUXUdsf8aXl53LPYBciaAf9ON2nuR, https://esm.sh/graphiql5.4.0?standaloneexternalreact,react-dom,graphiql/react,graphql: sha384-P5rs3WtMRYUHbkeUuomiB3Grin04e9jKjuOY5KMBdjnl/qOUaCALfnVqVpIL8, https://esm.sh/graphiql/plugin-explorer5.1.5: sha384-hIrTiRjlICooYpU/kh97YrhFmYbV5WhIa37reJgertKXzyaM6kzkJaDUlQWs9vb, https://esm.sh/graphiql/react0.39.0?standaloneexternalreact,react-dom,graphql,graphiql/toolkit,emotion/is-prop-valid: sha384-snSfFGTvNof5jyaw3xkRx7zsKRy9DWiljMvYXoozIwrhQv/h2pWOH81boYwk5P2, https://esm.sh/graphiql/toolkit0.12.1?standaloneexternalgraphql: sha384-cNTwZgIW33q7A4EZoCMqzcXdfVIc2VthQvJ0uDpRXERBWYuDKPVMzvdQU8x48o, https://esm.sh/graphql17.0.2: sha384-IPvlcmnvWT91sKqwbg9MxPXJUuPmSdwXCp22x6hcbBkAEhlfSKkMLR3v19K9iRUp } } /script script typemodule import React from react; import ReactDOM from react-dom/client; import { GraphiQL, HISTORY_PLUGIN } from graphiql; import { createGraphiQLFetcher } from graphiql/toolkit; import { explorerPlugin } from graphiql/plugin-explorer; import graphiql/setup-workers/esm.sh; const fetcher createGraphiQLFetcher({ url: https://countries.trevorblades.com, }); const plugins [HISTORY_PLUGIN, explorerPlugin()]; function App() { return React.createElement(GraphiQL, { fetcher, plugins, defaultEditorToolsVisibility: true, }); } const container document.getElementById(graphiql); const root ReactDOM.createRoot(container); root.render(React.createElement(App)); /script /head body div idgraphiql div classloadingLoading…/div /div /body /html对照旧 UMD 页面逐项检查时需要确认这些改动都落实了不再引用graphiql.js/graphiql.min.js/dist/index.umd.js这类 UMD 脚本也不再依赖全局变量样式改为 esm.sh 上的dist/style.css对应包内graphiql/style.css导出模块通过 importmap 解析?standalone标记会把模块及其dependencies不含peerDependencies打包进单个 JS 文件external列表则是声明哪些包复用 importmap 里别的条目emotion/is-prop-valid映射到空的data:URL是示例中注释明确说明的 shim用于消除 console 中module emotion/is-prop-valid not found的报错importmap 中的integrity字段对每个 esm.sh URL 做了内容校验版本号改动后 integrity 需要与示例保持一致。示例使用的是 GraphiQL 5.4.0、graphiql/plugin-explorer5.1.5、React 19.2.8、graphql17.0.2全部为固定版本号。如果你的部署环境允许直接照抄这组版本组合最稳妥自行换版本时integrity值必须相应更新否则校验会失败。GraphiQL 5 必须处理 Monaco worker这是 4.x 时代不存在的迁移项。5.0.0 迁移指南说明GraphiQL 5 需要为 Monaco 配置 worker而 ESM-based CDN 场景属于其中一类。上面示例采用的做法是引入一行import graphiql/setup-workers/esm.sh;这一行对应包内导出 packages/graphiql/src/setup-workers/esm.sh.ts最终转调graphiql/react/setup-workers/esm.sh在 esm.sh CDN 环境下完成 worker 装配。5.0.0 迁移指南中另给出了等价的底层写法即通过 esm.sh 的?worker查询参数把三个 Monaco worker 加载为 web worker再挂到globalThis.MonacoEnvironmentimport createJSONWorker from https://esm.sh/monaco-editor/esm/vs/language/json/json.worker.js?worker; import createGraphQLWorker from https://esm.sh/monaco-graphql/esm/graphql.worker.js?worker; import createEditorWorker from https://esm.sh/monaco-editor/esm/vs/editor/editor.worker.js?worker; globalThis.MonacoEnvironment { getWorker(_workerId, label) { switch (label) { case json: return createJSONWorker(); case graphql: return createGraphQLWorker(); } return createEditorWorker(); }, };两种写法二选一即可不要同时引入示例 HTML 用的是setup-workers一行导入。如果你维护的是 Vite 项目而非纯 CDN则对应的是另一条路径安装并配置vite-plugin-monaco-editor见同一份 5.0.0 迁移指南不属于本文的 CDN 场景。验证迁移结果examples/graphiql-cdn/README.md 给出的运行方式不需要任何安装或构建步骤——直接用浏览器打开index.htmlmacOSopen index.htmlLinuxfirefox index.html或chromium index.html打开后按下面几点判断迁移是否完成挂载节点被接管#graphiql容器内的 Loading… 占位内容被 GraphiQL 界面替换说明 importmap 解析、模块加载与渲染链路都通了任何 URL 拼错、版本不存在或 integrity 不匹配都会在这一步体现为加载失败。能执行查询示例的 fetcher 指向公共 GraphQL 端点https://countries.trevorblades.com发起一次查询应能拿到响应左侧侧边栏的 History 与 Explorer 插件图标可用说明HISTORY_PLUGIN与explorerPlugin()装配正确。没有 React 版本报错CDN 构建内置了版本检查见 packages/graphiql/src/cdn.ts当检测到 React 主版本低于 16 时会抛出明确错误并指回本示例的 importmap 写法。示例使用 React 19.2.8不在此列。console 干净emotion/is-prop-valid的 shim 生效后不应再出现module emotion /is-prop-valid not found报错该 shim 在示例 HTML 注释中说明了用途。限制与后续5.0.0 起编辑器从 CodeMirror 迁移到 Monaco行为有变化在操作编辑器里点击引用改为按住CmdmacOS或CtrlWindows/Linux生效query、variables、headers、response、readOnly、keyMap、validationRules等 props 已被移除其中前三个可用initialQuery、initialVariables、initialHeaders替代仅作用于第一个 tab。如果你的 UMD 页面里用到这些 props迁移时必须同步改造。示例中defaultEditorToolsVisibility: true用于让操作编辑器、变量等工具栏默认可见属于示例配置项可按需调整。插件包也有各自的 ESM CDN 示例可参考plugin-explorer 与 plugin-code-exporterUMD 构建在两个插件包里同样已被移除。5.0.0 起若你想替换或清空默认插件可用referencePlugin{null}加空的plugins数组移除 Doc Explorer 与 History保留 History 则需在plugins中显式写入HISTORY_PLUGIN本文示例即是这种保留写法。至此页面上不应再出现任何index.umd.js、graphiql.min.js之类的 UMD 引用全部依赖走 esm.sh 的 ESM URL并已通过浏览器直接打开 HTML 的方式验证了渲染与查询执行。【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考