零构建接入 GraphiQL基于 esm.sh CDN 与 Import Map 的纯浏览器集成指南【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql导读本指南基于仓库中的 examples/graphiql-cdn/README.md 与配套的 index.html 示例讲解如何完全跳过 npm 安装与构建步骤在一个静态 HTML 页面中通过 ESM 风格的 CDNesm.sh直接使用 GraphiQL并同时接入 GraphiQL Explorer 插件与 History 历史记录插件。读完本文你将掌握 Import Map 的依赖编排、?standalone打包参数的用法、Monaco 编辑器的 Worker 配置方式以及如何用createGraphiQLFetcher连接任意 GraphQL 端点——最终产出一个可直接双击打开、零依赖的 GraphQL 开发工具页面。这个示例解决什么问题在典型的前端工作流里使用 GraphiQL 需要npm install graphiql、配置打包器webpack / Vite / Parcel并处理样式与 Web Worker 等资源。仓库里确实提供了 graphiql-vite、graphiql-webpack、graphiql-create-react-app 等基于构建工具的示例但graphiql-cdn示例走的是另一条路无需安装、无需构建——直接双击index.html即可运行。它的实现方式是利用esm.sh这个以 ESM 形式提供 npm 包内容的 CDN配合浏览器原生的 Import Map 机制把 React、GraphiQL 及其插件全部在运行时加载。这在快速原型、文档站内嵌、离线演示、内部工具页面等场景下非常实用。快速开始三步跑起来按 examples/graphiql-cdn/README.md 的说明本示例没有任何 Setup 步骤只需要用浏览器打开示例目录下的index.htmlmacOSopen index.htmlLinuxfirefox index.html # 或 chromium index.html前提是浏览器支持 ESM 模块与 Import Map现代 Chrome / Edge / Firefox / Safari 均已支持。打开后页面顶部title中声明的内容——GraphiQL 5 with React 19 and GraphiQL Explorer——即最终的运行形态一个内置 GraphQL 操作编辑、变量编辑、响应查看、文档/历史面板与 Explorer 图形化探索器的完整 GraphiQL 界面。逐行拆解 index.html 的依赖编排整个示例只有一个 index.html约 100 行其核心是head中的两块样式表link与importmaptypemodule脚本。1. 两个必须的 CSS 文件link relstylesheet hrefhttps://esm.sh/graphiql5.4.0/dist/style.css integritysha384-... crossoriginanonymous / link relstylesheet hrefhttps://esm.sh/graphiql/plugin-explorer5.1.5/dist/style.css integritysha384-... crossoriginanonymous /graphiql5.4.0/dist/style.cssGraphiQL 主界面的样式编辑器、工具栏、面板布局等。graphiql/plugin-explorer5.1.5/dist/style.cssExplorer 插件的样式。两个link都带integritySRI 子资源完整性校验与crossoriginanonymous保证 CDN 内容在传输中被篡改时浏览器会拒绝加载。在 npm 工作流中这两个样式分别由import graphiql/style.css与import graphiql/plugin-explorer/style.css引入见 packages/graphiql-plugin-explorer/README.md 的 Usage 小节CDN 场景下则直接以 URL 形式引用 dist 产物。2. Import Map把裸模块名映射到 CDN URLscript 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: { ... } } /script这张表是整个方案的核心逐项拆解Import Map 键解析到的 CDN 地址作用react/react/esm.sh/react19.2.8React 核心/后缀用于解析 react 内部的子路径导入react-dom/react-dom/esm.sh/react-dom19.2.8React DOM 渲染器graphiql/graphiql/esm.sh/graphiql5.4.0GraphiQL 主组件与内置插件/用于graphiql/setup-workers/esm.sh这类子路径graphiql/plugin-exploreresm.sh/graphiql/plugin-explorer5.1.5Explorer 插件graphiql/reactesm.sh/graphiql/react0.39.0GraphiQL 的 React 层hooks、上下文、UI 组件graphiql/toolkitesm.sh/graphiql/toolkit0.12.1fetcher 等工具函数graphqlesm.sh/graphql17.0.2GraphQL.js 语言核心emotion/is-prop-validdata:text/javascript,空 shim消除底层依赖的 console 报错其中两个关键设计值得说明a?standalone参数的含义。正如 index.html 内注释所写?standalone会把该模块与其所有dependencies排除peerDependencies打包进一个独立的 JavaScript 文件。以graphiql为例它声明了graphiql/react、graphql等 peer 依赖这些通过external显式排除、由 Import Map 中的顶层入口共享而它自身的非 peer 依赖则被内联进 standalone bundle。bexternal与依赖共享。graphiql、graphiql/plugin-explorer、graphiql/react三个入口的external列表中react、react-dom、graphql反复出现graphiql/react与graphiql/toolkit也被逐层排除。这意味着整张 Import Map 中同一个库只加载一份实例React 只在esm.sh/react19.2.8出现一次GraphQL.js 只在esm.sh/graphql17.0.2出现一次GraphiQL 主包、Explorer 插件与graphiql/react之间通过共享的graphiql/react单例交换上下文避免出现两套 React / 两套 context导致的运行时崩溃。cemotion/is-prop-valid的 shim。该条目被映射为data:text/javascript,空模块。index.html 注释明确说明这是为了消除控制台错误module emotion/is-prop-valid not found上游问题见 motion 仓库 issue #3126。当某个 npm 包以 ESM 形式通过 CDN 运行时未声明的传递依赖经常需要这类空 shim 来占位。dintegrity 字段。Import Map 的integrity对象为每个 URL 提供了独立的 SRI 哈希与 CSS 的integrity属性共同构成对 CDN 内容的完整性校验链。3. 模块入口脚本组装应用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));各部分的职责GraphiQL与HISTORY_PLUGIN来自graphiql入口。HISTORY_PLUGIN在 packages/graphiql/src/index.ts 中被重新导出其实现位于 packages/graphiql-plugin-history/src/index.ts是一个标准GraphiQLPlugin对象title / icon / content 三要素提供历史查询记录面板。createGraphiQLFetcher来自graphiql/toolkit只需传入url即可生成 GraphiQL 所需的 fetcher。这里指向公共的 Countries GraphQL 服务https://countries.trevorblades.com你可以换成任何自己的 GraphQL 端点。explorerPlugin()来自graphiql/plugin-explorer返回 Explorer 插件实例。该插件基于 GraphiQL Explorer见 packages/graphiql-plugin-explorer/README.md提供图形化的 schema 浏览与查询构建能力。defaultEditorToolsVisibility: true默认展开底部编辑器工具区变量、Headers 等让首次打开的用户直接看到完整布局。React 18 的createRoot渲染方式挂载到div idgraphiql。HTML 中该容器初始内容为Loading…index.htmlReact 渲染完成后被真实界面替换。注意脚本使用的是React.createElement而非 JSX——这是因为该 HTML 没有经过任何构建工具无法编译 JSX因此全部用函数形式书写。4. Worker 配置Monaco 编辑器的多语言支持import graphiql/setup-workers/esm.sh;GraphiQL 底层的 Monaco 编辑器在解析 JSON / GraphQL 时依赖 Web Worker。这一行导入的就是面向 CDN 场景的 Worker 配置入口在 packages/graphiql/src/setup-workers/esm.sh.ts它复用了 packages/graphiql-react/src/setup-workers/esm.sh.ts 的实现——直接以https://esm.sh/monaco-editor0.52.2/esm/vs/...?worker形式加载 JSON、GraphQL、Editor 三类 Worker并设置globalThis.MonacoEnvironment.getWorker按语言标签json/graphql/ 默认返回对应的 Worker 实例。这个文件正是前面 Import Map 中graphiql/: https://esm.sh/graphiql5.4.0/的用途所在graphiql/setup-workers/esm.sh这个子路径导入被映射到https://esm.sh/graphiql5.4.0/setup-workers/esm.sh。在 npm 场景下Vite 与 webpack 用户则分别使用 setup-workers/vite.ts 与 setup-workers/webpack.ts。CDN 包的静态属性插件生态的共享基础在 esm.sh 上graphiql5.4.0的入口是 packages/graphiql/src/cdn.ts。该文件在默认导出上通过Object.assign附加了若干静态属性专门为 CDN 场景设计静态属性值说明createFetchercreateGraphiQLFetcher无需单独引入graphiql/toolkit即可创建 fetchercreateLocalStoragegraphiql/toolkit的createLocalStorage生成自定义命名的本地存储空间GraphQL完整的graphqlGraphQL.js导出供插件 CDN 包复用同一份 GraphQL.jsReactgraphiql/react的全部导出由于graphiql/react本来就打进 bundle顺带暴露出来供插件复用代码注释cdn.ts明确写道For the CDN bundle we add some static properties to the component function so that they can be accessed in the inline-script in the HTML file.——即这些属性是给 HTML 内联脚本用的。同时 cdn.ts 还有一个版本守卫若 React 主版本号小于 16直接抛错提示 GraphiQL 0.18.0 and after is not compatible with React 15 or below。这也解释了为什么 Import Map 中graphiql的external要包含graphiql/react和graphql插件如 Explorer通过external与graphiql共享这些依赖并复用GraphiQL.React暴露的同一套graphiql/react单例从而保证插件与主界面处于同一个 React 上下文。如何改成你自己的 GraphQL 服务把示例接入自有后端只需两步修改 fetcher 的urlconst fetcher createGraphiQLFetcher({ url: https://api.example.com/graphql, });createGraphiQLFetcher支持更多进阶选项如自定义 headers、subscription 端点、wsClient等完整类型与实现见 packages/graphiql-toolkit/src/create-fetcher/createFetcher.ts适用于 GraphQL over HTTP 与 GraphQL over WebSocket实时订阅场景。仓库内的 examples/graphiql-cdn 同级示例 还演示了如何在界面里动态切换服务端点。如需自定义本地存储命名空间可用 CDN 包暴露的静态方法// 假设通过全局变量拿到 CDN 暴露的 GraphiQL 构造器 const storage GraphiQL.createLocalStorage({ namespace: my-app });版本锁定与升级路径示例中所有依赖都显式锁定了精确版本react19.2.8、graphiql5.4.0、graphiql/plugin-explorer5.1.5、graphiql/react0.39.0、graphiql/toolkit0.12.1、graphql17.0.2。这是 CDN 方案的关键实践由于没有锁文件lockfile和构建期依赖解析手动维护的 Import Map 就是唯一的锁升级时需同步更新对应包的版本号CSS 链接、Import Map 中的 URLexternal列表中共享依赖的版本一致性例如升级graphiql主版本时通常需要同步升级graphiql/react并核对graphql主版本兼容性SRIintegrity哈希URL 变化后旧哈希会失效需重新计算。配套的 examples/graphiql-cdn/package.json 中只有一个脚本build-demo: copy index.html ../../packages/graphiql/cdn/它把本示例作为 GraphiQL 官方发布流程中 CDN 演示页的源头说明这份 HTML 本身就是经过实践验证的官方参考实现。从源码看整体架构闭环把本文涉及的文件串联起来可以看到一个完整的 CDN 使用闭环examples/graphiql-cdn/index.html # 唯一入口importmap 模块脚本 ├── 样式esm.sh/graphiql5.4.0/dist/style.css │ esm.sh/graphiql/plugin-explorer5.1.5/dist/style.css ├── 主组件graphiql → packages/graphiql/src/cdn.tsCDN 专用入口 │ ├── GraphiQL 组件packages/graphiql/src/GraphiQL.tsx │ ├── HISTORY_PLUGINpackages/graphiql-plugin-history/src/index.ts │ └── 静态属性 createFetcher / createLocalStorage / GraphQL / React ├── 插件graphiql/plugin-explorer → explorerPlugin()packages/graphiql-plugin-explorer/src/index.tsx ├── 工具graphiql/toolkit → createGraphiQLFetcherpackages/graphiql-toolkit/src/create-fetcher/createFetcher.ts └── Workergraphiql/setup-workers/esm.sh → packages/graphiql-react/src/setup-workers/esm.sh.ts其中 packages/graphiql/src/cdn.ts 是整个 CDN 方案的接线板它既校验 React 版本又把graphiql/react、graphql的实例作为静态属性暴露给插件侧复用。理解了这个文件就理解了为什么 Import Map 需要那张层层external的依赖表。小结本示例证明了 GraphiQL 的接入成本可以被压到极致一个 HTML 文件两次双击一个完整的 GraphQL IDE。其要点可归纳为用 esm.sh 的?standaloneexternal...组合生成可独立运行的模块配合 Import Map 实现多包共享同一份 React / GraphQL.js /graphiql/react实例用两条link引入 GraphiQL 与 Explorer 插件的样式并通过 SRI 保证 CDN 内容完整性用createGraphiQLFetcher一行接入任意 GraphQL 端点用HISTORY_PLUGIN与explorerPlugin()快速获得历史记录与图形化探索能力用graphiql/setup-workers/esm.sh完成 Monaco 编辑器在纯 ESM 环境下的 Worker 配置。如果你需要完整的多页面、路由或深度定制可以在此基础上转向仓库中的构建工具示例如 graphiql-vite、graphiql-nextjs、monaco-graphql-react-vite而如果你的诉求是最快速度在浏览器里跑起一个 GraphQL 工具本文的 CDN 方案就是最直接的答案。【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考