@graphiql/plugin-collections

中文文档
1.0.1发布于 2026/11/02MITTypeScriptCommonJS构建来源已验证近 30 天下载 5.8万

A first-party operation collections plugin for GraphiQL.

原始使用文档
文档目录8 节
  1. Installation
  2. Usage
  3. Options
  4. Import and merge behavior
  5. Custom storage
  6. Team-shared backends and sync
  7. Programmatic access
  8. Exports

@graphiql/plugin-collections

A first-party operation collections plugin for GraphiQL. Save named GraphQL operations into collections and reuse them later, with drag-and-drop reordering, clipboard sharing, and JSON import/export that merges by id instead of duplicating.

Installation

npm install @graphiql/plugin-collections

Make sure the peer dependencies are installed too:

npm install react react-dom graphql @graphiql/react

Usage

The collections plugin is installed by default in GraphiQL, so an unmodified <GraphiQL> already shows a Collections rail icon. Use COLLECTIONS_PLUGIN when you pass a custom plugins array and want to keep the default collections configuration. Use collectionsPlugin(options) to supply a custom storage backend or restrict what users can do.

Note: passing the plugins prop replaces the default plugin set, so include the others you want alongside it.

import { GraphiQL } from 'graphiql';
import { createTransport } from '@graphiql/toolkit';
import { COLLECTIONS_PLUGIN } from '@graphiql/plugin-collections';
import 'graphiql/style.css';
import '@graphiql/plugin-collections/style.css';

const transport = createTransport({
  url: 'https://swapi-graphql.netlify.app/.netlify/functions/index',
});

function GraphiQLWithCollections() {
  return <GraphiQL transport={transport} plugins={[COLLECTIONS_PLUGIN]} />;
}

Options

collectionsPlugin({
  storage, // custom persistence backend; see below
  readOnly, // default false
  allowImportExport, // default true
  allowReplace, // default true
});
OptionDefaultEffect
storagelocalStorage adapterA custom CollectionsStorage (see Custom storage).
readOnlyfalseHides every write affordance (create, rename, delete, reorder, save, import). Export and copy stay available so users can still share.
allowImportExporttrueWhen false, hides the import/export dialog button and turns off paste/drop import.
allowReplacetrueWhen false, hides the destructive "replace everything" import mode and leaves only merge.

Import and merge behavior

Collections and the operations inside them carry stable UUIDs that survive export and import. On import, the plugin reconciles by id instead of duplicating:

  • A new operation is added. An operation you already have is updated in place wherever you keep it, even if you've moved it to a different collection. A missing parent collection is recreated.
  • Re-importing an unchanged export does nothing, so you never get duplicates.
  • When an incoming operation differs from your local copy, a dialog lets you apply the changes, keep your versions, or review each operation one at a time. Merge never deletes.

An operation can also be shared on its own with "Copy operation". It travels as a one-item collection envelope stamped with its parent collection, so the recipient can re-home it on import.

Custom storage

Persistence is pluggable through the CollectionsStorage interface:

type CollectionsStorage = {
  storageKey?: string;
  load(): Promise<Collection[]>;
  save(collections: Collection[]): Promise<void>;
};

The default writes to localStorage under the key graphiql:collections. To use a different key, pass an adapter from the exported createLocalStorageAdapter factory:

import {
  collectionsPlugin,
  createLocalStorageAdapter,
} from '@graphiql/plugin-collections';

const collections = collectionsPlugin({
  storage: createLocalStorageAdapter('my-key'),
});

To back collections with your own service (REST, a database, a team-shared store), implement the interface and pass it as storage:

import { collectionsPlugin } from '@graphiql/plugin-collections';
import type {
  Collection,
  CollectionsStorage,
} from '@graphiql/plugin-collections';

const apiStorage: CollectionsStorage = {
  async load() {
    const res = await fetch('/api/collections');
    return (await res.json()) as Collection[];
  },
  async save(collections) {
    const response = await fetch('/api/collections', {
      method: 'PUT',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(collections),
    });
    if (!response.ok) {
      throw new Error(`Saving collections failed (${response.status})`);
    }
  },
};

const collections = collectionsPlugin({ storage: apiStorage });

load() runs once when the panel first mounts. save() receives the full collection list after mutations. For toolbar or keyboard saves, its promise must resolve only after the write commits. A rejection keeps the operation dirty and shows an error in GraphiQL. Other collection editing actions still update the UI immediately.

Team-shared backends and sync

The plugin has no opinion about conflict resolution or synchronization; that lives in your storage adapter. Because every operation and collection has a stable id, your adapter can diff successive save() snapshots and reconcile them however it needs to, whether that is a plain backend write, a last-write-wins policy, or a CRDT such as Yjs or Automerge. The plugin itself stays a CRUD UI over a serializable model.

The plugin does not react to remote changes on its own. When your backend reports an external change, call reload() to re-read storage and refresh the UI:

import { collectionsStore } from '@graphiql/plugin-collections';

await collectionsStore.getState().actions.reload();

Programmatic access

The store and its React hook are exported for programmatic access:

import {
  collectionsStore, // the vanilla zustand store
  useCollectionsStore, // React hook: useCollectionsStore(selector)
} from '@graphiql/plugin-collections';

const { actions } = collectionsStore.getState();

// Replace the in-memory collections (e.g. after merging remote state).
// Does NOT write back to storage.
actions.setCollections(nextCollections);

// Re-read from the configured storage and refresh the UI.
await actions.reload();

actions also exposes the full CRUD surface (createCollection, addItem, updateItem, deleteItem, moveItem, renameCollection, and so on) plus exportCollections / exportCollection / exportItem and the two-phase analyzeImport / applyImport.

Exports

  • COLLECTIONS_PLUGIN — the default plugin configuration
  • collectionsPlugin(options?) — the plugin factory for custom configuration
  • collectionsStore, useCollectionsStore — the store and its React hook
  • createLocalStorageAdapter(key), localStorageAdapter — built-in storage
  • CollectionsSaveDialog — the save dialog component
  • Types: Collection, CollectionItem, CollectionsStorage, CollectionsConfig, ActiveOperation

版本与发布记录

@graphiql/plugin-collections 共发布 10 个版本,首次发布于 2026/08/30;过去 12 个月发布了 10 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.0.1latest2026/11/0214 天前
1.0.02026/11/0115 天前
1.0.0-rc.1rc2026/09/301 个月前
1.0.0-rc.02026/09/281 个月前
1.0.0-beta.4beta2026/09/281 个月前
1.0.0-beta.32026/09/281 个月前

关于 @graphiql/plugin-collections 的常见问题

@graphiql/plugin-collections 是什么?

A first-party operation collections plugin for GraphiQL.

如何安装 @graphiql/plugin-collections?

在项目目录运行 npm install @graphiql/plugin-collections,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^18 || ^19)、graphql(^16.11.0 || ^17.0.0)、react-dom(^18 || ^19)、@graphiql/react(^1.0.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphiql/plugin-collections 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphiql/plugin-collections 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@graphiql/plugin-collections 可以商用吗?

@graphiql/plugin-collections 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphiql/plugin-collections 的下载量有多少?

根据 npm 官方下载统计,@graphiql/plugin-collections 在 2026/10/17 – 2026/11/15 这 30 天内被下载 57,562 次,日均约 1,919 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphiql/plugin-collections 还在维护吗?

最新版本 1.0.1 发布于 2026/11/02(14 天前);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/08/30。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。