storybook-addon-apollo-client - npm Package Compare versions

Comparing version 6.0.1--canary.112.cb0357d.0 to 7.0.0--canary.112.04472e9.0

package.json

		{
		"name": "storybook-addon-apollo-client",
		"version": "6.0.1--canary.112.cb0357d.0",
		"version": "7.0.0--canary.112.04472e9.0",
		"description": "Use Apollo Client in your Storybook stories.",
		@@ -5,0 +5,0 @@ "keywords": [

318

README.md

		# Storybook Addon Apollo Client

		Use Apollo Client in your Storybook stories.

		### Development scripts
		## Versions

		- `npm run start` runs babel in watch mode and starts Storybook
		- `npm run build` build and package your addon code
		- If you're using Apollo Client 2.x and Storybook 5.x use version 1.x
		- If you're using Apollo Client 2.x or 3.x and Storybook 6.x use version 4.x
		- If you're using Apollo Client 2.x or 3.x and Storybook 7.x use version 5.x
		- If you're using Apollo Client 2.x or 3.x and Storybook 8.x use version 7.x

		### Switch from TypeScript to JavaScript
		## Known issues

		Don't want to use TypeScript? We offer a handy eject command: `npm run eject-ts`
		due to how MockedProvider works in Apollo, you will have to hard refresh when visiting sub stories (visiting stories that exist in the same file) to get the expected results, please upvote my comment here to see if we can get this fixed: https://github.com/apollographql/apollo-client/issues/9738#issuecomment-1606316338

		This will convert all code to JS. It is a destructive process, so we recommended running this before you start writing any code.
		## Install

		## What's included?
		pnpm

		![Demo](https://user-images.githubusercontent.com/42671/107857205-e7044380-6dfa-11eb-8718-ad02e3ba1a3f.gif)
		```shell
		pnpm add -D storybook-addon-apollo-client
		```

		The addon code lives in `src`. It demonstrates all core addon related concepts. The three [UI paradigms](https://storybook.js.org/docs/react/addons/addon-types#ui-based-addons)
		yarn

		- `src/Tool.tsx`
		- `src/Panel.tsx`
		- `src/Tab.tsx`
		```shell
		yarn add -D storybook-addon-apollo-client
		```

		Which, along with the addon itself, are registered in `src/manager.ts`.
		npm

		Managing State and interacting with a story:
		```shell
		npm install -D storybook-addon-apollo-client
		```

		- `src/withGlobals.ts` & `src/Tool.tsx` demonstrates how to use `useGlobals` to manage global state and modify the contents of a Story.
		- `src/withRoundTrip.ts` & `src/Panel.tsx` demonstrates two-way communication using channels.
		- `src/Tab.tsx` demonstrates how to use `useParameter` to access the current story's parameters.
		Add the addon to your configuration in `.storybook/main.ts`

		Your addon might use one or more of these patterns. Feel free to delete unused code. Update `src/manager.ts` and `src/preview.ts` accordingly.
		```js
		export default {
		...config,
		addons: [
		...yourAddons
		"storybook-addon-apollo-client",
		],
		};
		```

		Lastly, configure you addon name in `src/constants.ts`.
		## 7.0 Features

		### Bundling
		- removed `globalMocks` key to favor composition

		Addons can interact with a Storybook project in multiple ways. It is recommended to familiarize yourself with [the basics](https://storybook.js.org/docs/react/addons/introduction) before getting started.
		### Migrate from 5.x+ to 7.x

		- Manager entries are used to add UI or behavior to the Storybook manager UI.
		- Preview entries are used to add UI or behavior to the preview iframe where stories are rendered.
		- Presets are used to modify the Storybook configuration, similar to how [users can configure their `main.ts` configurations](https://storybook.js.org/docs/react/api/main-config).
		#### Example of < 7.x

		Since each of these places represents a different environment with different features and modules, it is also recommended to split and build your modules accordingly. This addon-kit comes with a preconfigured [bundling configuration](./tsup.config.ts) that supports this split, and you are free to modify and extend it as needed.
		preview.ts

		You can define which modules match which environments in the [`package.json#bundler`](./package.json) property:

		- `exportEntries` is a list of module entries that users can manually import from anywhere they need to. For example, you could have decorators that users need to import into their `preview.ts` file or utility functions that can be used in their `main.ts` files.
		- `managerEntries` is a list of module entries meant only for the manager UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.
		- `previewEntries` is a list of module entries meant only for the preview UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.

		Manager and preview entries are only used in the browser so they only output ESM modules. Export entries could be used both in the browser and in Node depending on their use case, so they both output ESM and CJS modules.

		#### Globalized packages

		Storybook provides a predefined set of packages that are available in the manager UI and the preview UI. In the final bundle of your addon, these packages should not be included. Instead, the imports should stay in place, allowing Storybook to replace those imports with the actual packages during the Storybook build process.

		The list of packages differs between the manager and the preview, which is why there is a slight difference between `managerEntries` and `previewEntries`. Most notably, `react` and `react-dom` are prebundled in the manager but not in the preview. This means that your manager entries can use React to build UI without bundling it or having a direct reference to it. Therefore, it is safe to have React as a `devDependency` even though you are using it in production. _Requiring React as a peer dependency would unnecessarily force your users to install React._

		An exception to this rule is if you are using React to inject UI into the preview, which does not come prebundled with React. In such cases, you need to move `react` and `react-dom` to a peer dependency. However, we generally advise against this pattern since it would limit the usage of your addon to React-based Storybooks.

		### Metadata

		Storybook addons are listed in the [catalog](https://storybook.js.org/addons) and distributed via npm. The catalog is populated by querying npm's registry for Storybook-specific metadata in `package.json`. This project has been configured with sample data. Learn more about available options in the [Addon metadata docs](https://storybook.js.org/docs/react/addons/addon-catalog#addon-metadata).

		## Documentation

		To help the community use your addon and understand its capabilities, please document it thoroughly.

		To get started, replace this README with the content in this sample template, modeled after how essential addons (like [Actions](https://storybook.js.org/docs/essentials/actions)) are documented. Then update the content to describe your addon.

		### Sample documentation template

		````md
		# My Addon

		## Installation

		First, install the package.

		```sh
		npm install --save-dev my-addon
		```

		Then, register it as an addon in `.storybook/main.js`.

		```js
		// .storybook/main.ts
		import { MockedProvider } from "@apollo/client/testing"; // Use for Apollo Version 3+
		// import { MockedProvider } from "@apollo/react-testing"; // Use for Apollo Version < 3

		// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
		import type { StorybookConfig } from '@storybook/your-framework';

		const config: StorybookConfig = {
		// ...rest of config
		addons: [
		'@storybook/addon-essentials'
		'my-addon', // 👈 register the addon here
		],
		export const preview = {
		parameters: {
		apolloClient: {
		MockedProvider,
		globalMocks: [
		// whatever mocks you want here
		],
		},
		},
		};

		export default config;
		```

		## Usage
		#### Example of 7.x

		The primary way to use this addon is to define the `exampleParameter` parameter. You can do this the
		component level, as below, to affect all stories in the file, or you can do it for a single story.
		preview.ts

		```js
		// Button.stories.ts
		// Whatever you want here, but not Apollo Client related
		```

		// Replace your-framework with the name of your framework
		import type { Meta } from '@storybook/your-framework';
		component.stories.ts

		import { Button } from './Button';
		```ts
		import type { Meta } from "@storybook/react";
		import { globalMocks } from "./globalMocks";
		import { otherMocks } from "./otherMocks";
		import { YourComponent, YOUR_QUERY } from "./component";

		const meta: Meta<typeof Button> = {
		component: Button,
		export const meta: Meta<typeof DisplayLocation> = {
		component: YourComponent,
		parameters: {
		myAddon: {
		exampleParameter: true,
		// See API section below for available parameters
		}
		}
		apolloClient: {
		mocks: [
		...globalMocks,
		...otherMocks,
		{
		request: {
		query: YOUR_QUERY,
		},
		result: {
		data: {
		// your data here
		},
		},
		},
		],
		},
		},
		};

		export default meta;
		```

		Another way to use the addon is...
		## Upgrading from a previous version below 6.x

		## API
		In previous versions, we had a decorator called `withApolloClient` this is no longer nesscessary. If you're upgrading from this API here are the following changes that you'll need to make:

		### Parameters
		1. remove all code referencing the deprecated withApolloClient decorator.
		2. follow install instructions

		This addon contributes the following parameters to Storybook, under the `myAddon` namespace:
		## Writing your stories with queries

		#### `disable`
		```jsx
		import DashboardPage, { DashboardPageQuery } from ".";

		Type: `boolean`
		export default {
		title: "My Story",
		};

		Disable this addon's behavior. This parameter is most useful to allow overriding at more specific
		levels. For example, if this parameter is set to true at the project level, it could then be
		re-enabled by setting it to false at the meta (component) or story level.
		export const Example = () => <DashboardPage />;

		### Options

		When registering this addon, you can configure it with the following options, which are passed when
		registering the addon, like so:

		```ts
		// .storybook/main.ts

		// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
		import type { StorybookConfig } from '@storybook/your-framework';

		const config: StorybookConfig = {
		// ...rest of config
		addons: [
		'@storybook/essentials',
		{
		name: 'my-addon',
		options: {
		// 👈 options for my-addon go here
		Example.parameters = {
		apolloClient: {
		mocks: [
		{
		request: {
		query: DashboardPageQuery,
		},
		result: {
		data: {
		viewer: null,
		},
		},
		},
		},
		],
		],
		},
		};

		export default config;
		```

		#### `useExperimentalBehavior`
		Read more about the options available for MockedProvider at https://www.apollographql.com/docs/react/development-testing/testing

		Type: `boolean`
		### Usage

		Enable experimental behavior to...
		In Storybook, click "Show Addons" and navigate to the "Apollo Client" tab.

		````
		![Addon UI Preview](preview.png)

		## Release Management
		## Example App

		### Setup
		To see real world usage of how to use this addon, check out the example app:

		This project is configured to use [auto](https://github.com/intuit/auto) for release management. It generates a changelog and pushes it to both GitHub and npm. Therefore, you need to configure access to both:
		https://github.com/lifeiscontent/realworld

		- [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-access-tokens) Create a token with both _Read and Publish_ permissions.
		- [`GH_TOKEN`](https://github.com/settings/tokens) Create a token with the `repo` scope.
		## Loading State

		Then open your `package.json` and edit the following fields:
		You can use the `delay` parameter to simulate loading state.

		- `name`
		- `author`
		- `repository`
		```js
		import DashboardPage, { DashboardPageQuery } from ".";

		#### Local
		export default {
		title: "My Story",
		};

		To use `auto` locally create a `.env` file at the root of your project and add your tokens to it:
		export const Example = () => <DashboardPage />;

		```bash
		GH_TOKEN=<value you just got from GitHub>
		NPM_TOKEN=<value you just got from npm>
		Example.parameters = {
		apolloClient: {
		mocks: [
		{
		// Use `delay` parameter to increase loading time
		delay: 1000,
		request: {
		query: DashboardPageQuery,
		},
		result: {
		data: {},
		},
		},
		],
		},
		};
		```

		Lastly, create labels on GitHub. You’ll use these labels in the future when making changes to the package.
		## Error State

		```bash
		npx auto create-labels
		```
		You can use the `error` parameter to create error state.

		If you check on GitHub, you’ll now see a set of labels that `auto` would like you to use. Use these to tag future pull requests.
		```js
		import DashboardPage, { DashboardPageQuery } from ".";

		#### GitHub Actions
		export default {
		title: "My Story",
		};

		This template comes with GitHub actions already set up to publish your addon anytime someone pushes to your repository.
		export const Example = () => <DashboardPage />;

		Go to `Settings > Secrets`, click `New repository secret`, and add your `NPM_TOKEN`.

		### Creating a release

		To create a release locally you can run the following command, otherwise the GitHub action will make the release for you.

		```sh
		npm run release
		Example.parameters = {
		apolloClient: {
		mocks: [
		{
		request: {
		query: DashboardPageQuery,
		},
		error: new ApolloError("This is a mock network error"),
		},
		],
		},
		};
		```

		That will:

		- Build and package the addon code
		- Bump the version
		- Push a release to GitHub and npm
		- Push a changelog to GitHub

storybook-addon-apollo-client - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics