Registry /
testing / storybook-addon-apollo-client
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EVENTS
✓ import { EVENTS } from 'storybook-addon-apollo-client';
✗ const { EVENTS } = require('storybook-addon-apollo-client');
Used for communicating between the decorator and the addon panel. Modern Storybook (v10+) is ESM-only.
ApolloClientAddonState
✓ import type { ApolloClientAddonState } from 'storybook-addon-apollo-client';
✗ import { ApolloClientAddonState } from 'storybook-addon-apollo-client';
This is a TypeScript type definition, primarily used for type safety when defining the addon's state.
Addon Configuration
✓ export default {
addons: [
"storybook-addon-apollo-client",
],
};
✗ module.exports = {
addons: [
"storybook-addon-apollo-client",
],
};
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.
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.
import type { MockedResponse } from '@apollo/client/testing';
import { MockedProvider } from '@apollo/client/testing';
import { addons } from 'storybook/internal/preview-api';
import type { Preview } from '@storybook/react';
import { print } from 'graphql';
import { useEffect } from 'react';
import type { ApolloClientAddonState } from 'storybook-addon-apollo-client';
import { EVENTS } from 'storybook-addon-apollo-client';
const getMockName = (mockedResponse: MockedResponse) => {
if (mockedResponse.request.operationName) {
return mockedResponse.request.operationName;
}
const operationDefinition = mockedResponse.request.query.definitions.find(
(definition) => definition.kind === 'OperationDefinition',
);
if (operationDefinition?.name) {
return operationDefinition.name.value;
}
return `Unnamed`;
};
function stringifyOrUndefined(value: unknown) {
try {
return JSON.stringify(value, null, 2);
} catch {
return undefined;
}
}
function createResultFromMocks(mocks: MockedResponse[], activeIndex: number): ApolloClientAddonState {
const mock = mocks[activeIndex];
if (!mock) {
return {
activeIndex: -1,
options: mocks.map(getMockName),
query: undefined,
variables: undefined,
extensions: undefined,
context: undefined,
result: undefined,
error: undefined,
};
}
return {
options: mocks.map(getMockName),
activeIndex: activeIndex,
query: print(mock.request.query),
variables: stringifyOrUndefined(mock.request.variables),
extensions: stringifyOrUndefined(mock.request.extensions),
context: stringifyOrUndefined(mock.request.context),
result: stringifyOrUndefined(mock.result),
error: stringifyOrUndefined(mock.error),
};
}
const preview: Preview = {
decorators: [
(Story, context) => {
useEffect(() => {
const { mocks = [] } = context.parameters.apolloClient || {};
const channel = addons.getChannel();
const handleRequest = (activeIndex: number) => {
const state = createResultFromMocks(mocks, activeIndex);
channel.emit(EVENTS.RESULT, state);
};
handleRequest(mocks.length ? 0 : -1);
channel.on(EVENTS.REQUEST, handleRequest);
return () => {
channel.off(EVENTS.REQUEST, handleRequest);
};
}, [context.parameters.apolloClient]);
if (!context.parameters.apolloClient) {
return <Story />;
}
return (
<MockedProvider {...context.parameters.apolloClient}>
<Story />
</MockedProvider>
);
},
],
};
export default preview;
Debug
Known issues
breakingVersions 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.fixRefer 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.
affects: >=8.0.0
breakingIn 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.fixRemove 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`.
affects: >=7.0.0
breakingStorybook 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.fixEnsure 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+. affects: >=10.0.0
deprecatedThe `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.fixRemove all code referencing the deprecated `withApolloClient` decorator and follow the current installation and setup instructions in the README.
affects: <6.0.0 (when upgrading to >=6.0.0)
gotchaThere have been reports of Apollo queries persisting between separate stories when mocking, leading to inconsistent failures, especially for stories not using Apollo.fixIf 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.
affects: All
Errors
Common errors & fixes
globalMocks is not defined
Attempting to use the deprecated `globalMocks` configuration option, which was removed in v7.0.0.
fixRefactor 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.
Error: Cannot find module 'storybook/internal/preview-api'
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.
fixEnsure 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.
Error: Storybook's CommonJS distribution is no longer available. Please use the ESM distribution instead.
Using CommonJS `require()` syntax or an older Node.js version with Storybook 10+, which is ESM-only.
fixUpdate 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.
Audit
Dependencies
storybookrequiredThis is a Storybook addon and requires Storybook as a peer dependency for its core functionality and API integration.