{"id":15840,"library":"storybook-addon-apollo-client","title":"Storybook Addon Apollo Client","description":"This Storybook addon integrates Apollo Client into your Storybook stories, allowing developers to effectively test components that interact with GraphQL APIs. It is currently on version 10.0.0, which supports Apollo Client v3/v4 and Storybook 10+. The package has a relatively fast release cadence, often aligning its major versions with new releases of Storybook and React, requiring users to carefully manage their `storybook-addon-apollo-client` version to match their Storybook and Apollo Client installations. A key differentiator is its ability to expose GraphQL queries and responses in a dedicated Storybook addon panel, simplifying the debugging and visualization of data interactions within isolated components. It primarily achieves this by leveraging Apollo Client's `MockedProvider` and a custom Storybook decorator.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/lifeiscontent/storybook-addon-apollo-client","tags":["javascript","storybook-addon","data-state","apollo","popular","graphql","storybook-addons"],"install":[{"cmd":"npm install storybook-addon-apollo-client","lang":"bash","label":"npm"},{"cmd":"yarn add storybook-addon-apollo-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add storybook-addon-apollo-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Storybook addon and requires Storybook as a peer dependency for its core functionality and API integration.","package":"storybook","optional":false}],"imports":[{"note":"Used for communicating between the decorator and the addon panel. Modern Storybook (v10+) is ESM-only.","wrong":"const { EVENTS } = require('storybook-addon-apollo-client');","symbol":"EVENTS","correct":"import { EVENTS } from 'storybook-addon-apollo-client';"},{"note":"This is a TypeScript type definition, primarily used for type safety when defining the addon's state.","wrong":"import { ApolloClientAddonState } from 'storybook-addon-apollo-client';","symbol":"ApolloClientAddonState","correct":"import type { ApolloClientAddonState } from 'storybook-addon-apollo-client';"},{"note":"The addon is configured by adding its name to the `addons` array in `.storybook/main.ts`. Storybook v10+ requires main.ts to be valid ESM.","wrong":"module.exports = {\n  addons: [\n    \"storybook-addon-apollo-client\",\n  ],\n};","symbol":"Addon Configuration","correct":"export default {\n  addons: [\n    \"storybook-addon-apollo-client\",\n  ],\n};"}],"quickstart":{"code":"import type { MockedResponse } from '@apollo/client/testing';\nimport { MockedProvider } from '@apollo/client/testing';\nimport { addons } from 'storybook/internal/preview-api';\nimport type { Preview } from '@storybook/react';\nimport { print } from 'graphql';\nimport { useEffect } from 'react';\nimport type { ApolloClientAddonState } from 'storybook-addon-apollo-client';\nimport { EVENTS } from 'storybook-addon-apollo-client';\n\nconst getMockName = (mockedResponse: MockedResponse) => {\n  if (mockedResponse.request.operationName) {\n    return mockedResponse.request.operationName;\n  }\n\n  const operationDefinition = mockedResponse.request.query.definitions.find(\n    (definition) => definition.kind === 'OperationDefinition',\n  );\n\n  if (operationDefinition?.name) {\n    return operationDefinition.name.value;\n  }\n\n  return `Unnamed`;\n};\n\nfunction stringifyOrUndefined(value: unknown) {\n  try {\n    return JSON.stringify(value, null, 2);\n  } catch {\n    return undefined;\n  }\n}\n\nfunction createResultFromMocks(mocks: MockedResponse[], activeIndex: number): ApolloClientAddonState {\n  const mock = mocks[activeIndex];\n  if (!mock) {\n    return {\n      activeIndex: -1,\n      options: mocks.map(getMockName),\n      query: undefined,\n      variables: undefined,\n      extensions: undefined,\n      context: undefined,\n      result: undefined,\n      error: undefined,\n    };\n  }\n  return {\n    options: mocks.map(getMockName),\n    activeIndex: activeIndex,\n    query: print(mock.request.query),\n    variables: stringifyOrUndefined(mock.request.variables),\n    extensions: stringifyOrUndefined(mock.request.extensions),\n    context: stringifyOrUndefined(mock.request.context),\n    result: stringifyOrUndefined(mock.result),\n    error: stringifyOrUndefined(mock.error),\n  };\n}\n\nconst preview: Preview = {\n  decorators: [\n    (Story, context) => {\n      useEffect(() => {\n        const { mocks = [] } = context.parameters.apolloClient || {};\n        const channel = addons.getChannel();\n\n        const handleRequest = (activeIndex: number) => {\n          const state = createResultFromMocks(mocks, activeIndex);\n          channel.emit(EVENTS.RESULT, state);\n        };\n\n        handleRequest(mocks.length ? 0 : -1);\n\n        channel.on(EVENTS.REQUEST, handleRequest);\n\n        return () => {\n          channel.off(EVENTS.REQUEST, handleRequest);\n        };\n      }, [context.parameters.apolloClient]);\n\n      if (!context.parameters.apolloClient) {\n        return <Story />;\n      }\n\n      return (\n        <MockedProvider {...context.parameters.apolloClient}>\n          <Story />\n        </MockedProvider>\n      );\n    },\n  ],\n};\n\nexport default preview;","lang":"typescript","description":"This quickstart demonstrates the required `preview.ts`/`preview.tsx` setup for `storybook-addon-apollo-client` v10.x. It includes a decorator that integrates Apollo Client's `MockedProvider` and sets up event listeners to display GraphQL queries and responses in the Storybook addon panel, crucial for visualizing mock data interactions within your components."},"warnings":[{"fix":"Refer to the 'Versions' section in the package README and the Storybook migration guides for specific Storybook and React version compatibility requirements. Update `storybook-addon-apollo-client` and its peer dependencies accordingly.","message":"Versions 10.0.0, 9.0.0, and 8.0.0 introduce breaking changes, primarily related to Storybook and React version compatibility. Always consult the README's 'Versions' section for the correct `storybook-addon-apollo-client` version matching your Storybook and Apollo Client setup.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Remove all references to `globalMocks` from your Storybook configuration. Follow the 'Setup for version 10.x' instructions in the README, which demonstrate the current recommended decorator-based setup using `context.parameters.apolloClient.mocks`.","message":"In version 7.0.0, `globalMocks` was removed in favor of a new 'addon kit' migration strategy. Using `globalMocks` will no longer work and requires a refactor of your Storybook configuration.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure your Storybook configuration files (`main.ts`, `preview.ts`) are using ESM syntax (e.g., `export default {}` instead of `module.exports = {}`). Update your Node.js version to 20.16+ or 22.19+.","message":"Storybook 10, which `storybook-addon-apollo-client` v10.0.0 supports, is ESM-only. Your `.storybook/main.ts` and other configuration files must be valid ESM. Node.js versions 20.16+ or 22.19+ are required.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Remove all code referencing the deprecated `withApolloClient` decorator and follow the current installation and setup instructions in the README.","message":"The `withApolloClient` decorator, used in versions below 6.x, has been deprecated and is no longer necessary. Continuing to use it will lead to configuration issues.","severity":"deprecated","affected_versions":"<6.0.0 (when upgrading to >=6.0.0)"},{"fix":"If encountering persistence issues, ensure proper isolation between stories. Review your `MockedProvider` setup and consider if client instances or caches are inadvertently shared. This might require custom logic in your decorators to reset the Apollo Client cache or create fresh instances per story.","message":"There have been reports of Apollo queries persisting between separate stories when mocking, leading to inconsistent failures, especially for stories not using Apollo.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Refactor your Storybook `preview.ts` or `preview.tsx` to remove `globalMocks`. Implement the current decorator-based setup, providing mocks via `context.parameters.apolloClient.mocks` as shown in the v10.x setup guide.","cause":"Attempting to use the deprecated `globalMocks` configuration option, which was removed in v7.0.0.","error":"globalMocks is not defined"},{"fix":"Ensure your Storybook dependencies (e.g., `storybook`, `@storybook/react-vite`) are updated to compatible versions (e.g., `^10.0.0` for `storybook-addon-apollo-client` v10). Verify your `main.ts` and `preview.ts` are using ESM syntax. Run `npx storybook@latest doctor` to diagnose.","cause":"Incorrect or incompatible Storybook peer dependency version, or issues with Storybook's internal module resolution due to an outdated Storybook installation or a CJS/ESM mismatch.","error":"Error: Cannot find module 'storybook/internal/preview-api'"},{"fix":"Update your Storybook configuration files (`.storybook/main.ts`, `.storybook/preview.ts`) to use ESM `import`/`export` syntax. Ensure your Node.js version is 20.16+ or 22.19+ to support ESM.","cause":"Using CommonJS `require()` syntax or an older Node.js version with Storybook 10+, which is ESM-only.","error":"Error: Storybook's CommonJS distribution is no longer available. Please use the ESM distribution instead."}],"ecosystem":"npm"}