From 713dc02f3caadb8bc39fafc92db88fe43045fe1d Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Wed, 23 Nov 2022 14:28:14 -0600 Subject: [PATCH 1/3] Add `contribute/framework` doc --- docs/contribute/framework.md | 141 +++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/contribute/framework.md diff --git a/docs/contribute/framework.md b/docs/contribute/framework.md new file mode 100644 index 000000000000..57b32883809e --- /dev/null +++ b/docs/contribute/framework.md @@ -0,0 +1,141 @@ +--- +title: 'Contributing a Storybook framework' +--- + +A Storybook framework is a node package that enables out-of-the-box support for either a metaframework (like Next.js, NuxtJS, or SvelteKit) or a combination of a builder (Webpack or Vite) and a renderer (React, Angular, Vue, web components, etc). When the framework provides support for a metaframework, it also takes care of any additional configuration necessary to make Storybook behave as similarly as possible to apps generated by the metaframework. For example, `@storybook/nextjs` [recreates or mocks a number of features of Next.js apps](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/README.md#supported-features) inside Storybook. + +For your reference, you can view [all of the official Storybook frameworks](https://github.com/storybookjs/storybook/tree/next/code/frameworks), including their full source code and documentation. + +## How to make a framework + +### 1. Decide on a package name + +The name should start with `storybook-framework-` and then correspond to what your framework supports. For example, a framework targeting SvelteKit would be `storybook-framework-svelte-kit` and a framework targeting Stencil with Vite would be `storybook-framework-stencil-vite`. When not targeting a metaframework, the naming convention is `storybook-framework--`. + +### 2. Consider what your framework will need to do + +Remember, the goal is to make Storybook behave—out-of-the-box—as similarly as possible to the metaframework or builder-renderer combination you’re targeting. In particular for metaframeworks, this means attempting to recreate any builder or babel configuration provided by the metaframework. And you should try to do so in a way that respects existing project configuration as much as possible. + +The library or libraries your framework supports may have different major versions available. Carefully consider which versions of each library your framework will support. You will need to account for the changes within those different versions or split your framework into different versions/packages itself to support each library version. To help ongoing maintenance, please consider adding integration tests for the various library versions your framework supports. + +### 3. Write the README + +Before writing any code, we advise you to write up a helpful README. It should, at minimum, contain installation instructions and a list of available features. Use the [README for `@storybook/nextjs`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/README.md) as a template. By writing the documentation first, it becomes a guide for your other work. + +### 4. Author the framework itself + +A framework can contain the following parts: + +**`package.json`** ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/package.json)) + +Because a framework is a node package, it must contain a `package.json` file. Here’s a template you can use to start: + +
+package.json template + +```json +{ + "name": "", + "version": "1.0.0", + "description": "Storybook for or & ", + "keywords": [ + "Storybook", + "", + "", + "", + "", + "", + "" + ], + "homepage": "", + "bugs": { + "url": "https://github.com///issues" + }, + "repository": { + "type": "git", + "url": "https://github.com//.git", + "directory": "" + }, + "license": "MIT", + "exports": { + ".": { + "require": "./dist/index.js", + "import": "./dist/index.mjs", + "types": "./dist/index.d.ts" + }, + "./preset": { + "require": "./dist/preset.js", + "import": "./dist/preset.mjs", + "types": "./dist/preset.d.ts" + }, + "./preview.js": { + "require": "./dist/preview.js", + "import": "./dist/preview.mjs", + "types": "./dist/preview.d.ts" + }, + "./package.json": "./package.json" + }, + "main": "dist/index.js", + "module": "dist/index.mjs", + "types": "dist/index.d.ts", + "files": ["dist/**/*", "types/**/*", "README.md", "*.js", "*.d.ts"], + "scripts": { + "check": "tsc --noEmit", + "test": "..." + }, + "dependencies": { + "@storybook/addons": "^7.0.0", + "@storybook/core-common": "^7.0.0", + "@storybook/node-logger": "^7.0.0", + "@storybook/": "^7.0.0", + "@storybook/": "^7.0.0" + }, + "devDependencies": { + "typescript": "x.x.x", + "": "^x.x.x", + "": "^x.x.x" + }, + "peerDependencies": { + "@babel/core": "^x.x.x", + "@storybook/addon-actions": "^7.0.0", + "": "^x.x.x || ^x.x.x", + "": "^x.x.x || ^x.x.x", + "": "^x.x.x" + }, + "engines": { + "node": ">=16" + }, + "publishConfig": { + "access": "public" + } +} +``` + +A few notes on some of those properties: + +- `exports`: The root, `./preset`, and `package.json` exports are required. If your framework has a `preview.js`, then that is required as well. +- `types`: We strongly encourage you to author your framework in TypeScript and distribute the types. +- `dependencies` and `devDependencies`: These are just examples. Yours may look quite different. +- `peerDependencies`: If your framework provides support for multiple versions of the libraries you’re targeting, be sure that is represented here. + +
+ +**`preset.js`** ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts)) + +The [preset API](../addons/writing-presets) is where you will configure the Storybook core (which builder and renderer are used by your framework), the builder (via either the [`webpackFinal`](../builders/webpack#extending-storybooks-webpack-config) or [`viteFinal`](../builders/vite#configuration) export), babel (via the `babel` export), any necessary addons, and any available options for your framework. + +**`preview.js`** ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preview.tsx)) + +The (optional) [preview API](../configure/overview#configure-story-rendering) is where you configure the rendering of stories, such as global decorators or initializing some runtime config needed for your framework to behave as expected. If your framework requires this file, note that you also need to [configure the `previewAnnotations` in `preset.js`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts#L66-L69). + +**`types.ts`** ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/types.ts)) + +If you author your framework in TypeScript (recommended), you should export the type for `StorybookConfig` which reflects the available options of your framework. + +### 5. Test your framework + +Test it in a fresh project using a Storybook set up as close as possible to your framework. For example, for `@storybook/nextjs`, which uses React and Webpack5, start with a project that uses `@storybook/react` and `@storybook/builder-webpack5`. Follow the installation instructions from your README and ensure everything works as expected. Remember to test the various versions, configs, and options for the libraries you’re supporting. + +## Thank you + +We deeply appreciate your help in making Storybook work for more developers and the libraries in which they build. If you have any suggestions to improve this document, please use the “Edit” link below. From 6964feb924513da3f6b7cd312913945a8440727f Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Fri, 25 Nov 2022 09:53:59 -0600 Subject: [PATCH 2/3] Address feedback - Add bits about announcing and path to "official" status --- docs/contribute/framework.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contribute/framework.md b/docs/contribute/framework.md index 57b32883809e..ba54707e1141 100644 --- a/docs/contribute/framework.md +++ b/docs/contribute/framework.md @@ -136,6 +136,10 @@ If you author your framework in TypeScript (recommended), you should export the Test it in a fresh project using a Storybook set up as close as possible to your framework. For example, for `@storybook/nextjs`, which uses React and Webpack5, start with a project that uses `@storybook/react` and `@storybook/builder-webpack5`. Follow the installation instructions from your README and ensure everything works as expected. Remember to test the various versions, configs, and options for the libraries you’re supporting. +### 6. Let us know! + +Once it's fully tested and released, please let us know about your framework by either announcing it in the `#showcase` channel of the [Storybook Discord](https://discord.gg/storybook) or tweeting it and mentioning `@storybookjs`. It's our hope that well-made community frameworks can eventually move into the Storybook codebase and be considered "official" support. + ## Thank you We deeply appreciate your help in making Storybook work for more developers and the libraries in which they build. If you have any suggestions to improve this document, please use the “Edit” link below. From 316e37eb7b21865a8d8b37ad2c56228380821f1d Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Mon, 28 Nov 2022 10:55:17 -0700 Subject: [PATCH 3/3] Address feedback - Add link to TOC - Change 'Write the README' heading to 'Write the documentation" - Remove 'Thank you' section - Add 'Other ways to contribute' section - Update/add corresponding section on other relevant pages --- docs/contribute/code.md | 9 +++++++++ docs/contribute/documentation-updates.md | 9 +++++++++ docs/contribute/framework.md | 11 ++++++++--- docs/contribute/how-to-contribute.md | 4 ++-- docs/toc.js | 5 +++++ 5 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/contribute/code.md b/docs/contribute/code.md index 52099cc30c30..9d1b70fd0311 100644 --- a/docs/contribute/code.md +++ b/docs/contribute/code.md @@ -245,3 +245,12 @@ Once the PR is merged, the template will be generated on a nightly cadence and y It's troublesome to know which packages you'll change ahead of time, and watching them can be highly demanding, even on modern machines. If you're working on a powerful enough machine, you can use `yarn build --all --watch` instead of `yarn build`. + +## Other ways to contribute + +Learn about other ways you can contribute to Storybook. + +- [**Overview**](./how-to-contribute.md): General guidance +- [**Docs**](./documentation-updates.md): Typos, clarifications +- [**Addons**](./../addons/introduction.md): Build an addon and share it with the community +- [**Frameworks**](./framework.md): Integrate Storybook with your favorite library diff --git a/docs/contribute/documentation-updates.md b/docs/contribute/documentation-updates.md index 1f31af37570f..2e3a630585c7 100644 --- a/docs/contribute/documentation-updates.md +++ b/docs/contribute/documentation-updates.md @@ -21,3 +21,12 @@ Scroll down to the bottom of the document page on GitHub and describe what you c ## Create the pull request In the Storybook repository, create a pull request that describes changes and includes additional context that would help maintainers review. Once you submit the PR, a maintainer will guide you through the triage and merge process. + +## Other ways to contribute + +Learn about other ways you can contribute to Storybook. + +- [**Overview**](./how-to-contribute.md): General guidance +- [**Code**](./code.md): Features, bug fixes, dependency updates +- [**Addons**](./../addons/introduction.md): Build an addon and share it with the community +- [**Frameworks**](./framework.md): Integrate Storybook with your favorite library diff --git a/docs/contribute/framework.md b/docs/contribute/framework.md index ba54707e1141..565636962e28 100644 --- a/docs/contribute/framework.md +++ b/docs/contribute/framework.md @@ -18,7 +18,7 @@ Remember, the goal is to make Storybook behave—out-of-the-box—as similarly a The library or libraries your framework supports may have different major versions available. Carefully consider which versions of each library your framework will support. You will need to account for the changes within those different versions or split your framework into different versions/packages itself to support each library version. To help ongoing maintenance, please consider adding integration tests for the various library versions your framework supports. -### 3. Write the README +### 3. Write the documentation Before writing any code, we advise you to write up a helpful README. It should, at minimum, contain installation instructions and a list of available features. Use the [README for `@storybook/nextjs`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/README.md) as a template. By writing the documentation first, it becomes a guide for your other work. @@ -140,6 +140,11 @@ Test it in a fresh project using a Storybook set up as close as possible to your Once it's fully tested and released, please let us know about your framework by either announcing it in the `#showcase` channel of the [Storybook Discord](https://discord.gg/storybook) or tweeting it and mentioning `@storybookjs`. It's our hope that well-made community frameworks can eventually move into the Storybook codebase and be considered "official" support. -## Thank you +## Other ways to contribute -We deeply appreciate your help in making Storybook work for more developers and the libraries in which they build. If you have any suggestions to improve this document, please use the “Edit” link below. +Learn about other ways you can contribute to Storybook. + +- [**Overview**](./how-to-contribute.md): General guidance +- [**Code**](./code.md): Features, bug fixes, dependency updates +- [**Docs**](./documentation-updates.md): Typos, clarifications +- [**Addons**](./../addons/introduction.md): Build an addon and share it with the community diff --git a/docs/contribute/how-to-contribute.md b/docs/contribute/how-to-contribute.md index a8b56d5c85cc..4e079a212fcb 100644 --- a/docs/contribute/how-to-contribute.md +++ b/docs/contribute/how-to-contribute.md @@ -12,9 +12,9 @@ In the interest of fostering an open and welcoming environment, we as contributo - [**Code**](./code.md): Features, bug fixes, dependency updates - [**Docs**](./documentation-updates.md): Typos, clarifications -- [**Integrations**](./../api/new-frameworks.md): Integrate Storybook with your favorite library - [**Addons**](./../addons/introduction.md): Build an addon and share it with the community -- TODO +- [**Frameworks**](./framework.md): Integrate Storybook with your favorite library + ## Not sure how to get started? - [Chat in Discord #contributing](https://discord.gg/storybook) diff --git a/docs/toc.js b/docs/toc.js index ef495a5ddd90..367e490c5476 100644 --- a/docs/toc.js +++ b/docs/toc.js @@ -541,6 +541,11 @@ module.exports = { }, ], }, + { + pathSegment: 'framework', + title: 'Framework', + type: 'link', + }, { pathSegment: 'how-to-reproduce', title: 'Reproduce',