From a73a4c3db63fa74476965102907170884b18e1c6 Mon Sep 17 00:00:00 2001 From: Asad Ali Date: Mon, 9 Mar 2026 09:24:31 +0500 Subject: [PATCH 01/97] fix issue 33735: Global background + color styles affecting stories --- .../core/assets/server/base-preview-head.html | 147 +++++++++--------- 1 file changed, 73 insertions(+), 74 deletions(-) diff --git a/code/core/assets/server/base-preview-head.html b/code/core/assets/server/base-preview-head.html index dacc8ef5d52c..4f58f5d6346b 100644 --- a/code/core/assets/server/base-preview-head.html +++ b/code/core/assets/server/base-preview-head.html @@ -112,11 +112,11 @@ border-radius: 10px; background: rgb(247, 247, 247); color: rgb(46, 52, 56); + } - & * { - background: rgb(247, 247, 247); - color: rgb(46, 52, 56); - } + .sb-nopreview_main * { + background: rgb(247, 247, 247); + color: rgb(46, 52, 56); } .sb-nopreview_heading { @@ -147,84 +147,83 @@ border: 1px solid #ff0000; box-shadow: 0 0 64px rgba(0, 0, 0, 0.1); gap: 24px; + } - & ol { - padding-left: 18px; - margin: 0; - } + .sb-errordisplay_main ol { + padding-left: 18px; + margin: 0; + } - /* Redefine colors to ensure readability regardless of user-provided * selectors. */ - * { - background: white; - color: black; - } + /* Redefine colors to ensure readability regardless of user-provided * selectors. */ + .sb-errordisplay_main * { + background: white; + color: black; + } - & h1 { - font-family: Nunito Sans; - font-size: 22px; - font-weight: 400; - line-height: 30px; - font-weight: normal; - margin: 0; - - &::before { - content: ''; - display: inline-block; - width: 12px; - height: 12px; - background: #ff4400; - border-radius: 50%; - margin-right: 8px; - } - } + .sb-errordisplay_main h1 { + font-family: Nunito Sans; + font-size: 22px; + font-weight: 400; + line-height: 30px; + font-weight: normal; + margin: 0; + } - & p, - & ol { - font-family: Nunito Sans; - font-size: 14px; - font-weight: 400; - line-height: 19px; - margin: 0; - } + .sb-errordisplay_main h1::before { + content: ''; + display: inline-block; + width: 12px; + height: 12px; + background: #ff4400; + border-radius: 50%; + margin-right: 8px; + } - & li + li { - margin: 0; - padding: 0; - padding-top: 12px; - } + .sb-errordisplay_main p, + .sb-errordisplay_main ol { + font-family: Nunito Sans; + font-size: 14px; + font-weight: 400; + line-height: 19px; + margin: 0; + } - & a { - color: currentColor; - } + .sb-errordisplay_main li + li { + margin: 0; + padding: 0; + padding-top: 12px; + } - & .sb-errordisplay_code { - padding: 10px; - flex: 1; - background: #242424; - color: #c6c6c6; - box-sizing: border-box; - - font-size: 14px; - font-weight: 400; - line-height: 19px; - border-radius: 4px; - - font-family: - 'Operator Mono', 'Fira Code Retina', 'Fira Code', 'FiraCode-Retina', 'Andale Mono', - 'Lucida Console', Consolas, Monaco, monospace; - margin: 0; - overflow: auto; - - & code { - background-color: inherit; - color: inherit; - } - } + .sb-errordisplay_main a { + color: currentColor; + } - & .sb-errordisplay pre { - white-space: pre-wrap; - white-space: revert; - } + .sb-errordisplay_main .sb-errordisplay_code { + padding: 10px; + flex: 1; + background: #242424; + color: #c6c6c6; + box-sizing: border-box; + + font-size: 14px; + font-weight: 400; + line-height: 19px; + border-radius: 4px; + + font-family: + 'Operator Mono', 'Fira Code Retina', 'Fira Code', 'FiraCode-Retina', 'Andale Mono', + 'Lucida Console', Consolas, Monaco, monospace; + margin: 0; + overflow: auto; + } + + .sb-errordisplay_main .sb-errordisplay_code code { + background-color: inherit; + color: inherit; + } + + .sb-errordisplay_main .sb-errordisplay_code { + white-space: pre-wrap; } @-webkit-keyframes sb-rotate360 { From f04aacff6908ec4342257aef04a2f21e5224e033 Mon Sep 17 00:00:00 2001 From: Asad Ali Date: Mon, 9 Mar 2026 09:37:38 +0500 Subject: [PATCH 02/97] update issue according to coderabbitai --- code/core/assets/server/base-preview-head.html | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/code/core/assets/server/base-preview-head.html b/code/core/assets/server/base-preview-head.html index 4f58f5d6346b..864a60ee2701 100644 --- a/code/core/assets/server/base-preview-head.html +++ b/code/core/assets/server/base-preview-head.html @@ -160,6 +160,13 @@ color: black; } + /* Exclude error code block from the universal reset to preserve ANSI colors and dark theme */ + .sb-errordisplay_main .sb-errordisplay_code, + .sb-errordisplay_main .sb-errordisplay_code * { + background: #242424; + color: #c6c6c6; + } + .sb-errordisplay_main h1 { font-family: Nunito Sans; font-size: 22px; From 95112ec8c2f9724fe3889efa1928f815a36d79e6 Mon Sep 17 00:00:00 2001 From: Asad Ali Date: Mon, 9 Mar 2026 09:52:49 +0500 Subject: [PATCH 03/97] remove duplication font-weight and add quote on font-family --- code/core/assets/server/base-preview-head.html | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/code/core/assets/server/base-preview-head.html b/code/core/assets/server/base-preview-head.html index 864a60ee2701..2cebfeb7a833 100644 --- a/code/core/assets/server/base-preview-head.html +++ b/code/core/assets/server/base-preview-head.html @@ -168,11 +168,10 @@ } .sb-errordisplay_main h1 { - font-family: Nunito Sans; + font-family: 'Nunito Sans'; font-size: 22px; font-weight: 400; line-height: 30px; - font-weight: normal; margin: 0; } @@ -188,7 +187,7 @@ .sb-errordisplay_main p, .sb-errordisplay_main ol { - font-family: Nunito Sans; + font-family: 'Nunito Sans'; font-size: 14px; font-weight: 400; line-height: 19px; From d177fb1c27393cdf7bf1d4e4a10267a931d14000 Mon Sep 17 00:00:00 2001 From: Asad Ali Date: Mon, 9 Mar 2026 10:01:17 +0500 Subject: [PATCH 04/97] inherit font family --- code/core/assets/server/base-preview-head.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/core/assets/server/base-preview-head.html b/code/core/assets/server/base-preview-head.html index 2cebfeb7a833..4e2ca7f30ef6 100644 --- a/code/core/assets/server/base-preview-head.html +++ b/code/core/assets/server/base-preview-head.html @@ -168,7 +168,7 @@ } .sb-errordisplay_main h1 { - font-family: 'Nunito Sans'; + font-family: inherit; font-size: 22px; font-weight: 400; line-height: 30px; @@ -187,7 +187,7 @@ .sb-errordisplay_main p, .sb-errordisplay_main ol { - font-family: 'Nunito Sans'; + font-family: inherit; font-size: 14px; font-weight: 400; line-height: 19px; From baf7ac527177eb6e5bbd5c5f299801c42ff01c90 Mon Sep 17 00:00:00 2001 From: ia319 Date: Mon, 23 Mar 2026 18:37:12 +0800 Subject: [PATCH 05/97] fix(addons-docs): scope slugger to docs render - create a docs-scoped slugger context - preserve slug deduping within a single docs page - keep heading anchors stable across docs navigation --- code/addons/docs/src/blocks/blocks/Docs.tsx | 10 +++++++--- .../src/blocks/blocks/DocsSluggerContext.ts | 19 +++++++++++++++++++ .../addons/docs/src/blocks/blocks/Heading.tsx | 5 ++++- .../docs/src/blocks/blocks/Subheading.tsx | 4 +++- code/addons/docs/src/typings.d.ts | 10 ++++++++-- 5 files changed, 41 insertions(+), 7 deletions(-) create mode 100644 code/addons/docs/src/blocks/blocks/DocsSluggerContext.ts diff --git a/code/addons/docs/src/blocks/blocks/Docs.tsx b/code/addons/docs/src/blocks/blocks/Docs.tsx index dec138786ebf..3e34af2a4429 100644 --- a/code/addons/docs/src/blocks/blocks/Docs.tsx +++ b/code/addons/docs/src/blocks/blocks/Docs.tsx @@ -8,6 +8,7 @@ import type { Theme } from 'storybook/theming'; import { DocsContainer } from './DocsContainer'; import type { DocsContextProps } from './DocsContext'; import { DocsPage } from './DocsPage'; +import { createDocsSlugger, DocsSluggerContext } from './DocsSluggerContext'; export type DocsProps = { docsParameter: Parameters; @@ -23,10 +24,13 @@ export function Docs({ > = docsParameter.container || DocsContainer; const Page = docsParameter.page || DocsPage; + const slugger = createDocsSlugger(); return ( - - - + + + + + ); } diff --git a/code/addons/docs/src/blocks/blocks/DocsSluggerContext.ts b/code/addons/docs/src/blocks/blocks/DocsSluggerContext.ts new file mode 100644 index 000000000000..c508333679e4 --- /dev/null +++ b/code/addons/docs/src/blocks/blocks/DocsSluggerContext.ts @@ -0,0 +1,19 @@ +import type { Context } from 'react'; +import { createContext } from 'react'; + +import GithubSlugger from 'github-slugger'; + +export type DocsSlugger = GithubSlugger; + +export const createDocsSlugger = () => new GithubSlugger(); + +// Share the context on globalThis so provider/consumer pairs still match if bundling duplicates +// this module, which can happen with Vite-based docs builds. +if (globalThis && globalThis.__DOCS_SLUGGER_CONTEXT__ === undefined) { + globalThis.__DOCS_SLUGGER_CONTEXT__ = createContext(null); + globalThis.__DOCS_SLUGGER_CONTEXT__.displayName = 'DocsSluggerContext'; +} + +export const DocsSluggerContext: Context = globalThis + ? globalThis.__DOCS_SLUGGER_CONTEXT__ + : createContext(null); diff --git a/code/addons/docs/src/blocks/blocks/Heading.tsx b/code/addons/docs/src/blocks/blocks/Heading.tsx index d0b1c06894a4..08011454ada5 100644 --- a/code/addons/docs/src/blocks/blocks/Heading.tsx +++ b/code/addons/docs/src/blocks/blocks/Heading.tsx @@ -5,6 +5,7 @@ import { H2 } from 'storybook/internal/components'; import GithubSlugger from 'github-slugger'; +import { DocsSluggerContext } from './DocsSluggerContext'; import { HeaderMdx } from './mdx'; import { withMdxComponentOverride } from './with-mdx-component-override'; @@ -12,6 +13,7 @@ export interface HeadingProps { disableAnchor?: boolean; } +// Preserve the legacy singleton when Heading is rendered outside a Docs tree. export const slugs = new GithubSlugger(); const HeadingImpl: FC> = ({ @@ -22,7 +24,8 @@ const HeadingImpl: FC> = ({ if (disableAnchor || typeof children !== 'string') { return

{children}

; } - const tagID = slugs.slug(children.toLowerCase()); + const slugger = React.useContext(DocsSluggerContext) ?? slugs; + const tagID = slugger.slug(children.toLowerCase()); return ( {children} diff --git a/code/addons/docs/src/blocks/blocks/Subheading.tsx b/code/addons/docs/src/blocks/blocks/Subheading.tsx index 177ead07d057..391eaa1c29e3 100644 --- a/code/addons/docs/src/blocks/blocks/Subheading.tsx +++ b/code/addons/docs/src/blocks/blocks/Subheading.tsx @@ -5,6 +5,7 @@ import { H3 } from 'storybook/internal/components'; import type { HeadingProps } from './Heading'; import { slugs } from './Heading'; +import { DocsSluggerContext } from './DocsSluggerContext'; import { HeaderMdx } from './mdx'; import { withMdxComponentOverride } from './with-mdx-component-override'; @@ -12,7 +13,8 @@ const SubheadingImpl: FC> = ({ children, disable if (disableAnchor || typeof children !== 'string') { return

{children}

; } - const tagID = slugs.slug(children.toLowerCase()); + const slugger = React.useContext(DocsSluggerContext) ?? slugs; + const tagID = slugger.slug(children.toLowerCase()); return ( {children} diff --git a/code/addons/docs/src/typings.d.ts b/code/addons/docs/src/typings.d.ts index 468759c8ba22..9d33fc5cca78 100644 --- a/code/addons/docs/src/typings.d.ts +++ b/code/addons/docs/src/typings.d.ts @@ -3,8 +3,14 @@ declare module 'acorn-jsx'; declare module 'vue/dist/vue'; declare var FEATURES: import('storybook/internal/types').StorybookConfigRaw['features']; -declare var __DOCS_CONTEXT__: any; -declare var PREVIEW_URL: any; +declare var __DOCS_CONTEXT__: import('react').Context< + | import('storybook/internal/types').DocsContextProps + | null +>; +declare var __DOCS_SLUGGER_CONTEXT__: import('react').Context< + import('./blocks/blocks/DocsSluggerContext').DocsSlugger | null +>; +declare var PREVIEW_URL: string | undefined; declare var LOGLEVEL: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined; declare var TAGS_OPTIONS: import('storybook/internal/types').TagsOptions; From 736e4e287f891692c808a4ec2738955087912499 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Tue, 24 Mar 2026 10:27:43 +0100 Subject: [PATCH 06/97] Ci: add agent scan to detect automated accounts --- .github/workflows/agent-scan.yml | 70 ++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 .github/workflows/agent-scan.yml diff --git a/.github/workflows/agent-scan.yml b/.github/workflows/agent-scan.yml new file mode 100644 index 000000000000..48f67f67e051 --- /dev/null +++ b/.github/workflows/agent-scan.yml @@ -0,0 +1,70 @@ +name: agent-scan + +on: + pull_request_target: + types: + - opened + - reopened + +concurrency: + group: agent-scan-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + issues: write + pull-requests: write + +jobs: + agentscan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd + - name: Cache AgentScan analysis + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 + with: + path: .agentscan-cache + key: agentscan-cache-${{ github.actor }} + restore-keys: agentscan-cache- + - name: AgentScan + id: agentscan + uses: MatteoGabriele/agentscan-action@a584774dd15cabe6df4c6ab45fc43514a3b56b2d + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + skip-members: "dependabot,huang-julien,yannbf,Sidnioulz,kasperpeulen,valentinpalkovic,github-actions,ndelangen,shilman,JReinhold,ghengeveld,storybook-bot,kylegach" + agent-scan-comment: false + cache-path: .agentscan-cache + - name: Label flagged PR + if: contains(fromJSON('["automation","suspicious"]'), steps.agentscan.outputs.classification) && !contains(steps.agentscan.outputs.community-flagged, 'true') + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const prNumber = context.payload.pull_request.number; + const classification = '${{ steps.agentscan.outputs.classification }}'; + + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: prNumber, + labels: ['possible bot'], + }); + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: prNumber, + body: [ + + ].join('\n'), + }); + - name: Close community flagged accounts + if: steps.agentscan.outputs.community-flagged == 'true' + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const prNumber = context.payload.pull_request.number; + + await github.rest.pulls.update({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + state: 'closed', + }); \ No newline at end of file From ce6cbfe74dadbefc6508333c85d5b57d9a28f439 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Tue, 24 Mar 2026 14:49:11 +0100 Subject: [PATCH 07/97] fix: add missing members --- .github/workflows/agent-scan.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/agent-scan.yml b/.github/workflows/agent-scan.yml index 48f67f67e051..ec31899ae717 100644 --- a/.github/workflows/agent-scan.yml +++ b/.github/workflows/agent-scan.yml @@ -30,7 +30,7 @@ jobs: uses: MatteoGabriele/agentscan-action@a584774dd15cabe6df4c6ab45fc43514a3b56b2d with: github-token: ${{ secrets.GITHUB_TOKEN }} - skip-members: "dependabot,huang-julien,yannbf,Sidnioulz,kasperpeulen,valentinpalkovic,github-actions,ndelangen,shilman,JReinhold,ghengeveld,storybook-bot,kylegach" + skip-members: "dependabot,huang-julien,MichaelArestad,yannbf,vanessayuenn,jonniebigodes,Sidnioulz,kasperpeulen,valentinpalkovic,github-actions,ndelangen,shilman,JReinhold,ghengeveld,storybook-bot,kylegach" agent-scan-comment: false cache-path: .agentscan-cache - name: Label flagged PR From 48795aceb2fedaf78f8d0dddd4abac9304abd715 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Tue, 24 Mar 2026 15:04:21 +0100 Subject: [PATCH 08/97] fix: add Ari --- .github/workflows/agent-scan.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/agent-scan.yml b/.github/workflows/agent-scan.yml index ec31899ae717..ac501576cf29 100644 --- a/.github/workflows/agent-scan.yml +++ b/.github/workflows/agent-scan.yml @@ -30,7 +30,7 @@ jobs: uses: MatteoGabriele/agentscan-action@a584774dd15cabe6df4c6ab45fc43514a3b56b2d with: github-token: ${{ secrets.GITHUB_TOKEN }} - skip-members: "dependabot,huang-julien,MichaelArestad,yannbf,vanessayuenn,jonniebigodes,Sidnioulz,kasperpeulen,valentinpalkovic,github-actions,ndelangen,shilman,JReinhold,ghengeveld,storybook-bot,kylegach" + skip-members: "dependabot,AriPerkkio,huang-julien,MichaelArestad,yannbf,vanessayuenn,jonniebigodes,Sidnioulz,kasperpeulen,valentinpalkovic,github-actions,ndelangen,shilman,JReinhold,ghengeveld,storybook-bot,kylegach" agent-scan-comment: false cache-path: .agentscan-cache - name: Label flagged PR From 60b21131b8d03740bbd4d41683e374ccfdc22bc2 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Wed, 25 Mar 2026 22:07:21 -0600 Subject: [PATCH 09/97] Docs: Standardize formatting, add docs-review skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Unignore docs content from formatter - Run formatter on docs - Remove redundant sidebar title fields in frontmatter - Remove all unnecessary prettier-ignore-start/end directives - Some remain (mostly for MDX snippets), because oxfmt does not support start/end directives, but _does_ support prettier's πŸ€·πŸ»β€β™‚οΈ - https://oxc.rs/docs/guide/usage/formatter/ignoring.html#ignore-comments - Standardize newline treatment around and inside block-level elements (Callout, If, details, etc) - Replace all IfRenderer instances with If --- .agents/skills/docs-review/SKILL.md | 123 ++++++ .oxfmtrc.json | 6 +- .../button-story-with-addon-example.md | 4 +- .../component-story-custom-args-complex.md | 8 +- .../component-story-static-asset-cdn.md | 8 +- ...omponent-story-static-asset-with-import.md | 8 +- docs/_snippets/custom-docs-page.md | 6 +- docs/_snippets/list-story-reuse-data.md | 24 +- docs/_snippets/list-story-template.md | 8 +- docs/_snippets/list-story-unchecked.md | 8 +- .../my-component-story-basic-and-props.md | 8 +- docs/addons/addon-knowledge-base.mdx | 68 ++-- docs/addons/addon-migration-guide.mdx | 38 +- docs/addons/addon-types.mdx | 37 +- docs/addons/addons-api.mdx | 183 ++------- docs/addons/configure-addons.mdx | 4 +- docs/addons/index.mdx | 10 +- docs/addons/install-addons.mdx | 22 +- docs/addons/integration-catalog.mdx | 60 +-- docs/addons/writing-addons.mdx | 50 +-- docs/addons/writing-presets.mdx | 60 +-- docs/ai/best-practices.mdx | 17 +- docs/ai/index.mdx | 8 +- docs/ai/manifests.mdx | 34 +- docs/ai/mcp/api.mdx | 10 +- docs/ai/mcp/overview.mdx | 6 +- docs/ai/mcp/sharing.mdx | 14 +- docs/api/arg-types.mdx | 182 ++++----- docs/api/cli-options.mdx | 111 ++--- docs/api/csf/csf-next.mdx | 55 ++- docs/api/csf/index.mdx | 142 ++----- docs/api/doc-blocks/doc-block-argtypes.mdx | 42 +- docs/api/doc-blocks/doc-block-canvas.mdx | 73 ++-- .../api/doc-blocks/doc-block-colorpalette.mdx | 9 +- docs/api/doc-blocks/doc-block-controls.mdx | 48 +-- docs/api/doc-blocks/doc-block-description.mdx | 21 +- docs/api/doc-blocks/doc-block-icongallery.mdx | 13 +- docs/api/doc-blocks/doc-block-markdown.mdx | 31 +- docs/api/doc-blocks/doc-block-meta.mdx | 42 +- docs/api/doc-blocks/doc-block-primary.mdx | 9 +- docs/api/doc-blocks/doc-block-source.mdx | 72 ++-- docs/api/doc-blocks/doc-block-stories.mdx | 13 +- docs/api/doc-blocks/doc-block-story.mdx | 51 +-- docs/api/doc-blocks/doc-block-subtitle.mdx | 7 +- .../doc-blocks/doc-block-tableofcontents.mdx | 17 +- docs/api/doc-blocks/doc-block-title.mdx | 7 +- docs/api/doc-blocks/doc-block-typeset.mdx | 73 ++-- docs/api/doc-blocks/doc-block-unstyled.mdx | 31 +- docs/api/doc-blocks/doc-block-useof.mdx | 21 +- docs/api/doc-blocks/index.mdx | 3 +- docs/api/index.mdx | 11 +- docs/api/main-config/index.mdx | 3 +- docs/api/main-config/main-config-addons.mdx | 7 +- .../main-config/main-config-babel-default.mdx | 11 +- docs/api/main-config/main-config-babel.mdx | 13 +- docs/api/main-config/main-config-build.mdx | 33 +- docs/api/main-config/main-config-core.mdx | 46 +-- docs/api/main-config/main-config-docs.mdx | 11 +- docs/api/main-config/main-config-env.mdx | 7 +- docs/api/main-config/main-config-features.mdx | 23 +- .../api/main-config/main-config-framework.mdx | 7 +- docs/api/main-config/main-config-indexers.mdx | 385 +++++++++--------- .../api/main-config/main-config-log-level.mdx | 7 +- .../main-config/main-config-manager-head.mdx | 11 +- .../main-config-preview-annotations.mdx | 7 +- .../main-config/main-config-preview-body.mdx | 11 +- .../main-config/main-config-preview-head.mdx | 11 +- docs/api/main-config/main-config-refs.mdx | 15 +- .../main-config/main-config-static-dirs.mdx | 13 +- docs/api/main-config/main-config-stories.mdx | 29 +- docs/api/main-config/main-config-swc.mdx | 7 +- docs/api/main-config/main-config-tags.mdx | 3 +- .../main-config/main-config-typescript.mdx | 93 ++--- .../main-config/main-config-vite-final.mdx | 7 +- .../main-config/main-config-webpack-final.mdx | 7 +- docs/api/main-config/main-config.mdx | 53 ++- docs/api/new-frameworks.mdx | 35 +- docs/api/parameters.mdx | 65 ++- docs/api/portable-stories/index.mdx | 3 +- .../portable-stories-jest.mdx | 279 ++++++------- .../portable-stories-playwright.mdx | 240 +++++------ .../portable-stories-vitest.mdx | 288 +++++++------ docs/builders/builder-api.mdx | 44 +- docs/builders/index.mdx | 9 +- docs/builders/vite.mdx | 55 +-- docs/builders/webpack.mdx | 61 +-- docs/configure/environment-variables.mdx | 59 ++- docs/configure/index.mdx | 44 +- docs/configure/integration/compilers.mdx | 30 +- docs/configure/integration/eslint-plugin.mdx | 33 +- .../frameworks-feature-support.mdx | 191 +++++---- docs/configure/integration/frameworks.mdx | 32 +- .../integration/images-and-assets.mdx | 30 +- docs/configure/integration/index.mdx | 3 +- docs/configure/integration/typescript.mdx | 99 ++--- docs/configure/story-layout.mdx | 21 +- docs/configure/story-rendering.mdx | 35 +- docs/configure/styling-and-css.mdx | 315 +++++++------- docs/configure/telemetry.mdx | 79 ++-- .../user-interface/features-and-behavior.mdx | 121 +++--- docs/configure/user-interface/index.mdx | 3 +- .../user-interface/sidebar-and-urls.mdx | 35 +- .../user-interface/storybook-addons.mdx | 7 +- docs/configure/user-interface/theming.mdx | 79 +--- docs/configure/webpack.mdx | 50 +-- docs/contribute/RFC.mdx | 25 +- docs/contribute/code.mdx | 59 +-- .../documentation/documentation-updates.mdx | 12 +- docs/contribute/documentation/index.mdx | 3 +- .../contribute/documentation/new-snippets.mdx | 105 ++--- docs/contribute/framework.mdx | 165 ++++---- docs/contribute/how-to-reproduce.mdx | 30 +- docs/contribute/index.mdx | 20 +- docs/essentials/actions.mdx | 26 +- docs/essentials/backgrounds.mdx | 31 +- docs/essentials/controls.mdx | 260 ++++-------- docs/essentials/highlight.mdx | 67 ++- docs/essentials/index.mdx | 23 +- docs/essentials/measure-and-outline.mdx | 5 +- docs/essentials/themes.mdx | 13 - docs/essentials/toolbars-and-globals.mdx | 69 +--- docs/essentials/viewport.mdx | 97 ++--- docs/faq.mdx | 237 ++++++----- docs/get-started/browse-stories.mdx | 32 +- docs/get-started/conclusion.mdx | 7 +- docs/get-started/frameworks/angular.mdx | 140 ++++--- docs/get-started/frameworks/index.mdx | 4 +- docs/get-started/frameworks/nextjs-vite.mdx | 165 ++------ docs/get-started/frameworks/nextjs.mdx | 198 +++------ docs/get-started/frameworks/preact-vite.mdx | 37 +- .../frameworks/react-native-web-vite.mdx | 76 ++-- docs/get-started/frameworks/react-vite.mdx | 40 +- .../get-started/frameworks/react-webpack5.mdx | 48 +-- docs/get-started/frameworks/svelte-vite.mdx | 74 +--- docs/get-started/frameworks/sveltekit.mdx | 119 ++---- docs/get-started/frameworks/vue3-vite.mdx | 55 ++- .../frameworks/web-components-vite.mdx | 27 +- docs/get-started/index.mdx | 2 +- docs/get-started/install.mdx | 351 ++++++++-------- docs/get-started/setup.mdx | 51 ++- docs/get-started/whats-a-story.mdx | 41 +- docs/get-started/why-storybook.mdx | 38 +- docs/releases/features.mdx | 10 +- docs/releases/index.mdx | 9 +- .../migration-guide-from-older-version.mdx | 104 +++-- docs/releases/migration-guide.mdx | 32 +- docs/releases/roadmap.mdx | 3 +- docs/releases/upgrading.mdx | 100 ++--- docs/sharing/design-integrations.mdx | 29 +- docs/sharing/embed.mdx | 65 +-- docs/sharing/index.mdx | 13 +- docs/sharing/package-composition.mdx | 11 +- docs/sharing/publish-storybook.mdx | 85 ++-- docs/sharing/storybook-composition.mdx | 38 +- docs/writing-docs/autodocs.mdx | 113 ++--- docs/writing-docs/build-documentation.mdx | 23 +- docs/writing-docs/code-panel.mdx | 1 - docs/writing-docs/doc-blocks.mdx | 62 ++- docs/writing-docs/index.mdx | 2 +- docs/writing-docs/mdx.mdx | 113 ++--- docs/writing-stories/args.mdx | 98 ++--- .../build-pages-with-storybook.mdx | 106 ++--- docs/writing-stories/decorators.mdx | 107 ++--- docs/writing-stories/index.mdx | 161 +++----- docs/writing-stories/loaders.mdx | 23 +- .../mocking-data-and-modules/index.mdx | 3 +- .../mocking-modules.mdx | 65 ++- .../mocking-network-requests.mdx | 54 +-- .../mocking-providers.mdx | 57 ++- .../naming-components-and-hierarchy.mdx | 59 +-- docs/writing-stories/parameters.mdx | 45 +- docs/writing-stories/play-function.mdx | 11 +- .../stories-for-multiple-components.mdx | 49 +-- docs/writing-stories/tags.mdx | 23 +- docs/writing-stories/typescript.mdx | 83 ++-- docs/writing-tests/accessibility-testing.mdx | 53 +-- docs/writing-tests/in-ci.mdx | 76 ++-- docs/writing-tests/index.mdx | 89 ++-- docs/writing-tests/integrations/index.mdx | 3 +- .../stories-in-end-to-end-tests.mdx | 44 +- .../integrations/stories-in-unit-tests.mdx | 74 ++-- .../integrations/test-runner.mdx | 268 ++++-------- .../integrations/vitest-addon/index.mdx | 80 ++-- .../vitest-addon/migration-guide.mdx | 9 +- docs/writing-tests/interaction-testing.mdx | 37 +- docs/writing-tests/snapshot-testing.mdx | 33 +- docs/writing-tests/test-coverage.mdx | 25 +- docs/writing-tests/visual-testing.mdx | 21 +- 188 files changed, 4152 insertions(+), 6250 deletions(-) create mode 100644 .agents/skills/docs-review/SKILL.md diff --git a/.agents/skills/docs-review/SKILL.md b/.agents/skills/docs-review/SKILL.md new file mode 100644 index 000000000000..273252ac5047 --- /dev/null +++ b/.agents/skills/docs-review/SKILL.md @@ -0,0 +1,123 @@ +--- +name: docs-review +description: Guide for reviewing and maintaining documentation. Use this when asked to review or update documentation. +--- + +# Documentation Review Guide + +## Scope + +ONLY review and maintain documentation files, such as README.md, CONTRIBUTING.md, and docs/ directory. Do NOT review or edit code files, configuration files, or any non-documentation files. + +## Common gotchas + +- All relative links to other documentation files should point to the `.mdx` file and resolve correctly. If a link is broken, alert the author. +- All `paths` used by `` components should exist in the `docs/_snippets` directory. If a `path` does not exist, alert the author. +- Use `` instead of `` + +## Formatting + +Most formatting is handled automatically by scripts. These are opinionated guidelines to ensure consistency and readability across documentation files. When making edits, please follow these guidelines to maintain a high standard of documentation. + +### Frontmatter + +- Values are not wrapped in quotes, unless the value contains special characters (e.g. colons, commas) that require quoting to be parsed correctly. +- Only use `sidebar.title` when it is different from the `title` field. If `sidebar.title` is not needed, it should be omitted. + +**Good example:** + +```yaml +--- +title: Component Story Format (CSF) +sidebar: + title: CSF + order: 2 +--- +``` + +**Bad example:** + +```yaml +--- +title: "ArgTypes" +sidebar: + title: "ArgTypes" + order: 2 +--- +``` + +### Block JSX elements (e.g. ,
, ) + +- New line before and after elements (unless the content before/after is a comment, in which case there should be no new line between the comment and the element) +- New line before and after content inside elements ( is an exception, there should be no new line between the opening
tag and the tag) +- Content is not indented, except when the content would normally be indented (e.g. nested list items, content inside codeblocks) + +**Good example:** + +````mdx + + +Other content. + + + +This is a callout. + +- This is a list item inside the callout + - This is a nested list item inside the callout + +```json +{ + "key": "value" +} +``` + + + +More other content. + +
+This is a summary + +This is content inside the details element. + +
+ +More other content. + + +{/* End supported renderers */} +```` + +**Bad example:** + +````mdx + +Other content. + + +This is a callout. + +- This is a list item inside the callout +- This is a nested list item inside the callout + +```json +{ + "key": "value" +} +``` + + +More other content. +
+ +This is a summary +This is content inside the details element. + +
+More other content. + + + +{/* End supported renderers */} +```` diff --git a/.oxfmtrc.json b/.oxfmtrc.json index fa3458fee14e..0ce399e12812 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -36,12 +36,14 @@ "*.yaml", "*.md", "*.mdx", - "!docs/_snippets/**" + "!docs/**", + "docs/versions/**" ], "overrides": [ { - "files": ["docs/_snippets/**"], + "files": ["docs/**"], "options": { + "singleQuote": true, "trailingComma": "all" } }, diff --git a/docs/_snippets/button-story-with-addon-example.md b/docs/_snippets/button-story-with-addon-example.md index 40486d812154..e1d369e4faca 100644 --- a/docs/_snippets/button-story-with-addon-example.md +++ b/docs/_snippets/button-story-with-addon-example.md @@ -203,7 +203,7 @@ export const Basic: Story = { }); - + ``` ```js filename="Button.stories.js" renderer="svelte" language="js" tabTitle="CSF 3" @@ -248,7 +248,7 @@ export const Basic = {}; }); - + ``` ```ts filename="Button.stories.ts" renderer="svelte" language="ts" tabTitle="CSF 3" diff --git a/docs/_snippets/component-story-custom-args-complex.md b/docs/_snippets/component-story-custom-args-complex.md index 96f181e8a585..b2e6199e15e3 100644 --- a/docs/_snippets/component-story-custom-args-complex.md +++ b/docs/_snippets/component-story-custom-args-complex.md @@ -448,7 +448,7 @@ export const ExampleStory = { }; }, template: - '', + '', }; }, args: { @@ -499,7 +499,7 @@ export const ExampleStory: Story = { }; }, template: - '', + '', }; }, args: { @@ -720,7 +720,7 @@ export const ExampleStory = meta.story({ }; }, template: - '', + '', }; }, args: { @@ -770,7 +770,7 @@ export const ExampleStory = meta.story({ }; }, template: - '', + '', }; }, args: { diff --git a/docs/_snippets/component-story-static-asset-cdn.md b/docs/_snippets/component-story-static-asset-cdn.md index 6b753c1d8b9c..b07ef430b274 100644 --- a/docs/_snippets/component-story-static-asset-cdn.md +++ b/docs/_snippets/component-story-static-asset-cdn.md @@ -196,7 +196,7 @@ export default { export const WithAnImage = { render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }; ``` @@ -216,7 +216,7 @@ type Story = StoryObj; export const WithAnImage: Story = { render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }; ``` @@ -233,7 +233,7 @@ const meta = preview.meta({ export const WithAnImage = meta.story({ render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }); ``` @@ -252,7 +252,7 @@ const meta = preview.meta({ export const WithAnImage = meta.story({ render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }); ``` diff --git a/docs/_snippets/component-story-static-asset-with-import.md b/docs/_snippets/component-story-static-asset-with-import.md index 7db4cf01e027..3d3b4ca1e657 100644 --- a/docs/_snippets/component-story-static-asset-with-import.md +++ b/docs/_snippets/component-story-static-asset-with-import.md @@ -258,7 +258,7 @@ export const WithAnImage = { //πŸ‘‡ Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }; ``` @@ -288,7 +288,7 @@ export const WithAnImage: Story = { //πŸ‘‡ Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }; ``` @@ -315,7 +315,7 @@ export const WithAnImage = meta.story({ //πŸ‘‡ Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }); ``` @@ -344,7 +344,7 @@ export const WithAnImage = meta.story({ //πŸ‘‡ Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }); ``` diff --git a/docs/_snippets/custom-docs-page.md b/docs/_snippets/custom-docs-page.md index 32e344dfc44f..3227fe830987 100644 --- a/docs/_snippets/custom-docs-page.md +++ b/docs/_snippets/custom-docs-page.md @@ -61,15 +61,15 @@ If you didn't include the title in the story's default export, use this approach ### Primary - + ### Secondary - + ### Large - + ### Small diff --git a/docs/_snippets/list-story-reuse-data.md b/docs/_snippets/list-story-reuse-data.md index f462701e7e61..a0acd4c3a40f 100644 --- a/docs/_snippets/list-story-reuse-data.md +++ b/docs/_snippets/list-story-reuse-data.md @@ -304,9 +304,9 @@ export const ManyItems = { }, template: ` - - - + + + `, }), args: { @@ -340,9 +340,9 @@ export const ManyItems: Story = { }, template: ` - - - + + + `, }), args: { @@ -373,9 +373,9 @@ export const ManyItems = meta.story({ }, template: ` - - - + + + `, }), args: { @@ -408,9 +408,9 @@ export const ManyItems = meta.story({ }, template: ` - - - + + + `, }), args: { diff --git a/docs/_snippets/list-story-template.md b/docs/_snippets/list-story-template.md index 503fac6fd92b..b12d98463d73 100644 --- a/docs/_snippets/list-story-template.md +++ b/docs/_snippets/list-story-template.md @@ -370,7 +370,7 @@ const ListTemplate = { template: `
- +
`, @@ -417,7 +417,7 @@ export const ListTemplate: Story = { template: `
- +
`, @@ -460,7 +460,7 @@ export const Empty = meta.story({ template: `
- +
`, @@ -501,7 +501,7 @@ export const Empty = meta.story({ template: `
- +
`, diff --git a/docs/_snippets/list-story-unchecked.md b/docs/_snippets/list-story-unchecked.md index de9f24fed7ad..fa1e77b3f2b6 100644 --- a/docs/_snippets/list-story-unchecked.md +++ b/docs/_snippets/list-story-unchecked.md @@ -198,7 +198,7 @@ export const OneItem = { //πŸ‘‡ The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), }; ``` @@ -231,7 +231,7 @@ export const OneItem: Story = { //πŸ‘‡ The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), args: { ...Unchecked.args, @@ -264,7 +264,7 @@ export const OneItem = meta.story({ //πŸ‘‡ The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), args: { ...Unchecked.input.args, @@ -299,7 +299,7 @@ export const OneItem = meta.story({ //πŸ‘‡ The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), args: { ...Unchecked.input.args, diff --git a/docs/_snippets/my-component-story-basic-and-props.md b/docs/_snippets/my-component-story-basic-and-props.md index 38294f8af1c4..06d09ceee5c9 100644 --- a/docs/_snippets/my-component-story-basic-and-props.md +++ b/docs/_snippets/my-component-story-basic-and-props.md @@ -251,7 +251,7 @@ export const Basic = { export const WithProp = { render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }; ``` @@ -278,7 +278,7 @@ export const Basic: Story = { export const WithProp: Story = { render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }; ``` @@ -302,7 +302,7 @@ export const Basic = meta.story({ export const WithProp = meta.story({ render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }); ``` @@ -326,7 +326,7 @@ export const Basic = meta.story({ export const WithProp = meta.story({ render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }); ``` diff --git a/docs/addons/addon-knowledge-base.mdx b/docs/addons/addon-knowledge-base.mdx index 5dd7c2387d6e..fbe8767c0c84 100644 --- a/docs/addons/addon-knowledge-base.mdx +++ b/docs/addons/addon-knowledge-base.mdx @@ -13,20 +13,12 @@ It’s possible to disable the addon panel for a particular story. To make that possible, you need to pass the `paramKey` element when you register the panel: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Then when adding a story, you can pass a disabled parameter. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Style your addon Storybook uses [Emotion](https://emotion.sh/docs/introduction) for styling. Alongside with a theme that you can customize! @@ -38,41 +30,41 @@ If you don’t want to use Emotion, you can use inline styles or another css-in- Addon authors can develop their UIs using any React library. But we recommend using Storybook’s UI components in `storybook/internal/components` to build addons faster. When you use Storybook components, you get: -* Battle-tested off-the-shelf components -* Storybook native look and feel -* Built-in support for Storybook theming +- Battle-tested off-the-shelf components +- Storybook native look and feel +- Built-in support for Storybook theming Use the components listed below with your next addon. -| Component | Source | Story | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| Action Bar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ActionBar/ActionBar.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-actionbar--single-item) | -| Addon Panel | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/addon-panel/addon-panel.tsx) | N/A | -| Badge | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Badge/Badge.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-badge--all-badges) | -| Button | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Button/Button.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-button--all-buttons) | -| Form | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/form/index.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-form-button--sizes) | -| Loader | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Loader/Loader.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-loader--progress-bar) | -| PlaceHolder | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/placeholder/placeholder.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-placeholder--single-child) | -| Scroll Area | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ScrollArea/ScrollArea.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-scrollarea--vertical) | -| Space | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/spaced/Spaced.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-spaced--row) | -| Syntax Highlighter | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/syntaxhighlighter/syntaxhighlighter.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-syntaxhighlighter--bash) | -| Tabs | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tabs/tabs.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tabs--stateful-static) | -| ToolBar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/bar/bar.tsx) | N/A | -| ToolTip | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tooltip/Tooltip.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tooltip-tooltip--basic-default) | -| Zoom | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Zoom/Zoom.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-zoom--element-actual-size) | +| Component | Source | Story | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Action Bar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ActionBar/ActionBar.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-actionbar--single-item) | +| Addon Panel | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/addon-panel/addon-panel.tsx) | N/A | +| Badge | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Badge/Badge.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-badge--all-badges) | +| Button | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Button/Button.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-button--all-buttons) | +| Form | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/form/index.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-form-button--sizes) | +| Loader | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Loader/Loader.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-loader--progress-bar) | +| PlaceHolder | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/placeholder/placeholder.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-placeholder--single-child) | +| Scroll Area | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ScrollArea/ScrollArea.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-scrollarea--vertical) | +| Space | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/spaced/Spaced.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-spaced--row) | +| Syntax Highlighter | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/syntaxhighlighter/syntaxhighlighter.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-syntaxhighlighter--bash) | +| Tabs | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tabs/tabs.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tabs--stateful-static) | +| ToolBar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/bar/bar.tsx) | N/A | +| ToolTip | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tooltip/Tooltip.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tooltip-tooltip--basic-default) | +| Zoom | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Zoom/Zoom.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-zoom--element-actual-size) | Complementing the components, also included is a set of UI primitives. Use the content listed below as a reference for styling your addon. -| Component | Source | Story | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------- | -| Color Palette (see note below) | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/src/blocks/components/ColorPalette.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-colorpalette--page) | -| Icon | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/icon/icon.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels) | -| Typography | [See implementation](https://github.com/storybookjs/storybook/tree/next/code/core/src/components/components/typography) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all) | +| Component | Source | Story | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Color Palette (see note below) | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/src/blocks/components/ColorPalette.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-colorpalette--page) | +| Icon | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/icon/icon.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels) | +| Typography | [See implementation](https://github.com/storybookjs/storybook/tree/next/code/core/src/components/components/typography) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all) | - The color palette implemented by `@storybook/addon-docs/blocks` is a high-level abstraction of the [`storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/core/src/theming) module. - +The color palette implemented by `@storybook/addon-docs/blocks` is a high-level abstraction of the [`storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/core/src/theming) module. + ## Build system @@ -88,7 +80,9 @@ When you're developing your addon as a package, you can’t use `npm link` to ad ``` - Run either `yarn` or `npm install` to install the addon. + +Run either `yarn` or `npm install` to install the addon. + ## Hot module replacement @@ -115,10 +109,6 @@ If you're developing a local Storybook addon built on top of an existing Storybo If you're working on a preset that loads third-party addons, which you don't have control over, and you need access to certain features (e.g., decorators) or provide additional configurations. In that case, you'll need to update your preset to the following to allow you to load and configure the other addons: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - If you have control over the addons you want to customize. In that case, you can update your preset and implement a custom function to load any additional presets and provide the necessary configuration. diff --git a/docs/addons/addon-migration-guide.mdx b/docs/addons/addon-migration-guide.mdx index ca15e5876ca3..a6abb969960f 100644 --- a/docs/addons/addon-migration-guide.mdx +++ b/docs/addons/addon-migration-guide.mdx @@ -8,7 +8,9 @@ sidebar: We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 10.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 9.x to 10.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 9.0](../../../release-9-1/docs/addons/addon-migration-guide.mdx). - We also have a general [Storybook migration guide](../releases/migration-guide.mdx) that covers updates to your Storybook instance rather than your addon code. + +We also have a general [Storybook migration guide](../releases/migration-guide.mdx) that covers updates to your Storybook instance rather than your addon code. + ## Dependency updates @@ -20,11 +22,11 @@ You will need to update your Storybook dependencies. Peer dependencies must poin "devDependencies": { "@storybook/addon-docs": "next", "@storybook/react-vite": "next", - "storybook": "next" + "storybook": "next", }, "peerDependencies": { - "storybook": "^10.0.0" - } + "storybook": "^10.0.0", + }, } ``` @@ -38,15 +40,16 @@ If your addon supports multiple major versions of Storybook, you can specify a w { "name": "your-storybook-addon", "peerDependencies": { - "storybook": "^9.0.0 || ^10.0.0" + "storybook": "^9.0.0 || ^10.0.0", }, "devDependencies": { - "storybook": ">=10.0.0-0 <11.0.0-0" // For local development - } + "storybook": ">=10.0.0-0 <11.0.0-0", // For local development + }, } ``` However, we recommend releasing a new major version of your addon alongside new major versions of Storybook. This practice: + 1. Makes it easier to maintain your code 2. Allows you to take advantage of new features and improvements 3. Provides a clearer upgrade path for your users @@ -60,11 +63,12 @@ Here are the changes in version 10.0 that impact addon development. Storybook 10 requires all addons to be built as ESM-only. This change simplifies the build process and reduces maintenance overhead. You'll need to make many changes to `tsup.config.ts`, so it can be easier to copy the reference file in the [`addon-kit` repository](https://github.com/storybookjs/addon-kit/blob/main/tsup.config.ts). This update brings the following changes: -* The Node target moves from Node 20.0 to Node 20.19 -* You no longer need to build CJS files -* You no longer need to pass `globalManagerPackages` and `globalPreviewPackages` -* The `bundler` config in `package.json` no longer needs to be manually typed -* We recommend you stop using `exportEntries` and switch exported entries to `previewEntries` and `managerEntries` instead based on where they are consumed by your users + +- The Node target moves from Node 20.0 to Node 20.19 +- You no longer need to build CJS files +- You no longer need to pass `globalManagerPackages` and `globalPreviewPackages` +- The `bundler` config in `package.json` no longer needs to be manually typed +- We recommend you stop using `exportEntries` and switch exported entries to `previewEntries` and `managerEntries` instead based on where they are consumed by your users ```diff title="tsup.config.ts" - import { readFile } from "node:fs/promises"; @@ -259,21 +263,20 @@ Finally, change the `preset.js` file at the top-level of your addon to be ESM. T Because addons are now ESM-only, you must change how you load your own addon in your development Storybook instance. Imports and exports must now follow ESM syntax, and relative paths must use `import.meta.resolve`. - Remove `.storybook/local-preset.cjs` and create `.storybook/local-preset.ts` with the following content: ```ts title=".storybook/local-preset.ts" -import { fileURLToPath } from "node:url"; +import { fileURLToPath } from 'node:url'; export function previewAnnotations(entry = []) { - return [...entry, fileURLToPath(import.meta.resolve("../dist/preview.js"))]; + return [...entry, fileURLToPath(import.meta.resolve('../dist/preview.js'))]; } export function managerEntries(entry = []) { - return [...entry, fileURLToPath(import.meta.resolve("../dist/manager.js"))]; + return [...entry, fileURLToPath(import.meta.resolve('../dist/manager.js'))]; } -export * from "../dist/preset.js"; +export * from '../dist/preset.js'; ``` Next, update your `main.ts` to reference the new preset file: @@ -288,6 +291,7 @@ Next, update your `main.ts` to reference the new preset file: The following changes are not strictly required yet, but we recommend making them to improve your users' experience. ### CSF Factories support + To support CSF Factories annotations in your addon, you will need to update your `src/index.ts` file to use the new `definePreviewAddon`. This feature will be part of [CSF Next](../api/csf/csf-next.mdx). This change is highly recommended, as it will help your own users reap the benefits of CSF Factories. With CSF Factories, users can chain their preview configuration and benefit from better typing and more flexibility. Addons must export annotations to be compatible with this new syntax. CSF Factories will be the default way to write stories in Storybook 11. diff --git a/docs/addons/addon-types.mdx b/docs/addons/addon-types.mdx index f8d5b48f3a3e..b81d6864b7d6 100644 --- a/docs/addons/addon-types.mdx +++ b/docs/addons/addon-types.mdx @@ -1,8 +1,7 @@ --- -title: 'Types of addons' +title: Types of addons sidebar: order: 6 - title: Types of addons --- Each Storybook addon is classified into two general categories, UI-based or Presets. Each type of addons feature is documented here. Use this as a reference when creating your addon. @@ -19,12 +18,8 @@ Panel addons allow you to add your own UI in Storybook's addon panel. This is th Use this boilerplate code to add a new `Panel` to Storybook's UI: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Toolbars Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. For example, the official [`@storybook/addon-themes`](https://storybook.js.org/addons/@storybook/addon-themes) uses this pattern. @@ -33,14 +28,12 @@ Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. Fo Use this boilerplate code to add a new `button` to Storybook's Toolbar: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.mdx#conditionally-render-the-addon). The `icon` element used in the example loads the icons from the `storybook/internal/components` module. See [here](../faq.mdx#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. + +The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.mdx#conditionally-render-the-addon). The `icon` element used in the example loads the icons from the `storybook/internal/components` module. See [here](../faq.mdx#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. + ### Tabs @@ -51,14 +44,12 @@ Tab addons allow you to create your own custom tabs in Storybook. Use this boilerplate code to add a new `Tab` to Storybook's UI: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - Learn how to write your own addon that includes these UI elements [here](./writing-addons.mdx). + +Learn how to write your own addon that includes these UI elements [here](./writing-addons.mdx). + ## Preset addons @@ -67,16 +58,12 @@ Storybook preset addons are grouped collections of `babel`, `webpack`, and `addo Use this boilerplate code while writing your own preset addon. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - **Learn more about the Storybook addon ecosystem** -* Types of addons for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* [Presets](./writing-presets.mdx) for preset development -* [Integration catalog](./integration-catalog.mdx) for requirements and available recipes -* [API reference](./addons-api.mdx) to learn about the available APIs +- Types of addons for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- [Presets](./writing-presets.mdx) for preset development +- [Integration catalog](./integration-catalog.mdx) for requirements and available recipes +- [API reference](./addons-api.mdx) to learn about the available APIs diff --git a/docs/addons/addons-api.mdx b/docs/addons/addons-api.mdx index d2b518e44adb..454123eea161 100644 --- a/docs/addons/addons-api.mdx +++ b/docs/addons/addons-api.mdx @@ -1,8 +1,7 @@ --- -title: 'Addon API' +title: Addon API sidebar: order: 8 - title: Addon API --- Storybook's API allows developers to interact programmatically with Storybook. With the API, developers can build and deploy custom addons and other tools that enhance Storybook's functionality. @@ -11,43 +10,33 @@ Storybook's API allows developers to interact programmatically with Storybook. W Our API is exposed via two distinct packages, each one with a different purpose: -* `storybook/manager-api` used to interact with the Storybook manager UI or access the Storybook API. -* `storybook/preview-api` used to control and configure the addon's behavior. - -{/* prettier-ignore-start */} +- `storybook/manager-api` used to interact with the Storybook manager UI or access the Storybook API. +- `storybook/preview-api` used to control and configure the addon's behavior. -{/* prettier-ignore-end */} - ### addons.add() The `add` method allows you to register the type of UI component associated with the addon (e.g., panels, toolbars, tabs). For a minimum viable Storybook addon, you should provide the following arguments: -* `type`: The type of UI component to register. -* `title`: The title to feature in the Addon Panel. -* `render`: The function that renders the addon's UI component. - -{/* prettier-ignore-start */} +- `type`: The type of UI component to register. +- `title`: The title to feature in the Addon Panel. +- `render`: The function that renders the addon's UI component. -{/* prettier-ignore-end */} - - The render function is called with `active`. The `active` value will be true when the panel is focused on the UI. + +The render function is called with `active`. The `active` value will be true when the panel is focused on the UI. + ### addons.register() Serves as the entry point for all addons. It allows you to register an addon and access the Storybook [API](#storybook-api). For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Now you'll get an instance to our StorybookAPI. See the [api docs](#storybook-api) for Storybook API regarding using that. ### addons.getChannel() @@ -56,34 +45,28 @@ Get an instance to the channel to communicate with the manager and the preview. It has a NodeJS [EventEmitter](https://nodejs.org/api/events.html) compatible API. So, you can use it to emit events and listen to events. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### makeDecorator Use the `makeDecorator` API to create decorators in the style of the official addons. Like so: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called. + +If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called. + The `makeDecorator` API requires the following arguments: -* `name`: Unique name to identify the custom addon decorator. -* `parameterName`: Sets a unique parameter to be consumed by the addon. -* `skipIfNoParametersOrOptions`: (Optional) Doesn't run the decorator if the user hasn't options either via [decorators](../writing-stories/decorators.mdx) or [parameters](../writing-stories/parameters.mdx). -* `wrapper`: your decorator function. Takes the `getStory`, `context`, and both the `options` and `parameters` (as defined in `skipIfNoParametersOrOptions` above). +- `name`: Unique name to identify the custom addon decorator. +- `parameterName`: Sets a unique parameter to be consumed by the addon. +- `skipIfNoParametersOrOptions`: (Optional) Doesn't run the decorator if the user hasn't options either via [decorators](../writing-stories/decorators.mdx) or [parameters](../writing-stories/parameters.mdx). +- `wrapper`: your decorator function. Takes the `getStory`, `context`, and both the `options` and `parameters` (as defined in `skipIfNoParametersOrOptions` above). -*** +--- ## Storybook API @@ -93,68 +76,40 @@ Storybook's API allows you to access different functionalities of Storybook UI. The `selectStory` API method allows you to select a single story. It accepts the following two parameters; story kind name and an optional story name. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - This is how you can select the above story: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.selectInCurrentKind() Similar to the `selectStory` API method, but it only accepts the story as the only parameter. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.setQueryParams() This method allows you to set query string parameters. You can use that as temporary storage for addons. Here's how you define query params: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Additionally, if you need to remove a query parameter, set it as `null` instead of removing them from the addon. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getQueryParam() Allows retrieval of a query parameter enabled via the `setQueryParams` API method. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getUrlState(overrideParams) This method allows you to get the application URL state, including any overridden or custom parameter values. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getStoryHrefs(storyId, options?) Get the manager and preview URLs for a story. URLs are relative to the current Storybook, unless `base` is set, or in case of previewHref with `refId` set. @@ -168,22 +123,14 @@ Get the manager and preview URLs for a story. URLs are relative to the current S - `refId`: ID of the ref to get the URL for (for composed Storybooks) - `viewMode`: The view mode to use, defaults to 'story'. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.on(eventName, fn) This method allows you to register a handler function called whenever the user navigates between stories. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.openInEditor(payload) Opens a file in the configured code editor. Useful for "Edit in IDE" functionality in addons. @@ -194,77 +141,53 @@ Opens a file in the configured code editor. Useful for "Edit in IDE" functionali Returns a Promise that resolves with information about whether the operation was successful. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getCurrentStoryData() Returns the current story's data, including its ID, kind, name, and parameters. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.toggleFullscreen(toggled?) Toggles the fullscreen mode of the Storybook UI. Pass `true` to enable fullscreen, `false` to disable, or omit to toggle the current state. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.togglePanel(toggled?) Toggles the visibility of the addon panel. Pass `true` to show the panel, `false` to hide, or omit to toggle the current state. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.addNotification(notification) Displays a notification in the Storybook UI. The notification object should contain `id`, `content`, and optionally `duration` and `icon`. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### addons.setConfig(config) This method allows you to override the default Storybook UI configuration (e.g., set up a [theme](../configure/user-interface/theming.mdx) or hide UI elements): -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - The following table details how to use the API values: -| Name | Type | Description | Example Value | -| --------------------- | --------------- | ------------------------------------------------------- | ------------------------------------- | -| **navSize** | Number (pixels) | The size of the sidebar that shows a list of stories | `300` | -| **bottomPanelHeight** | Number (pixels) | The size of the addon panel when in the bottom position | `200` | -| **rightPanelWidth** | Number (pixels) | The size of the addon panel when in the right position | `200` | -| **panelPosition** | String | Where to show the addon panel | `'bottom'` or `'right'` | -| **enableShortcuts** | Boolean | Enable/disable shortcuts | `true` | -| **showToolbar** | Boolean | Show/hide toolbar | `true` | -| **theme** | Object | Storybook Theme, see next section | `undefined` | -| **selectedPanel** | String | Id to select an addon panel | `storybook/actions/panel` | -| **initialActive** | String | Select the default active tab on Mobile | `sidebar` or `canvas` or `addons` | -| **sidebar** | Object | Sidebar options, see below | `{ showRoots: false }` | -| **toolbar** | Object | Modify the tools in the toolbar using the addon id | `{ fullscreen: { hidden: false } }` | +| Name | Type | Description | Example Value | +| --------------------- | --------------- | ------------------------------------------------------- | ----------------------------------- | +| **navSize** | Number (pixels) | The size of the sidebar that shows a list of stories | `300` | +| **bottomPanelHeight** | Number (pixels) | The size of the addon panel when in the bottom position | `200` | +| **rightPanelWidth** | Number (pixels) | The size of the addon panel when in the right position | `200` | +| **panelPosition** | String | Where to show the addon panel | `'bottom'` or `'right'` | +| **enableShortcuts** | Boolean | Enable/disable shortcuts | `true` | +| **showToolbar** | Boolean | Show/hide toolbar | `true` | +| **theme** | Object | Storybook Theme, see next section | `undefined` | +| **selectedPanel** | String | Id to select an addon panel | `storybook/actions/panel` | +| **initialActive** | String | Select the default active tab on Mobile | `sidebar` or `canvas` or `addons` | +| **sidebar** | Object | Sidebar options, see below | `{ showRoots: false }` | +| **toolbar** | Object | Modify the tools in the toolbar using the addon id | `{ fullscreen: { hidden: false } }` | The following options are configurable under the `sidebar` namespace: @@ -276,11 +199,11 @@ The following options are configurable under the `sidebar` namespace: The following options are configurable under the `toolbar` namespace: -| Name | Type | Description | Example Value | -| --------- | ------ | -------------------------------------------------------------------- | ------------------- | -| **[id]** | String | Toggle visibility for a specific toolbar item (e.g. `title`, `zoom`) | `{ hidden: false }` | +| Name | Type | Description | Example Value | +| -------- | ------ | -------------------------------------------------------------------- | ------------------- | +| **[id]** | String | Toggle visibility for a specific toolbar item (e.g. `title`, `zoom`) | `{ hidden: false }` | -*** +--- ## Storybook hooks @@ -290,78 +213,50 @@ To help streamline addon development and reduce boilerplate code, the API expose It allows access to Storybook's internal state. Similar to the [`useglobals`](#useglobals) hook, we recommend optimizing your addon to rely on [`React.memo`](https://react.dev/reference/react/memo), or the following hooks; [`useMemo`](https://react.dev/reference/react/useMemo), [`useCallback`](https://react.dev/reference/react/useCallback) to prevent a high volume of re-render cycles. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useStorybookApi The `useStorybookApi` hook is a convenient helper to allow you full access to the [Storybook API](#storybook-api) methods. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useChannel Allows setting subscriptions to events and getting the emitter to emit custom events to the channel. The messages can be listened to on both the iframe and the manager. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useAddonState The `useAddonState` is a useful hook for addons that require data persistence, either due to Storybook's UI lifecycle or for more complex addons involving multiple types (e.g., toolbars, panels). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useParameter The `useParameter` retrieves the current story's parameters. If the parameter's value is not defined, it will automatically default to the second value defined. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useGlobals Extremely useful hook for addons that rely on Storybook [Globals](../essentials/toolbars-and-globals.mdx). It allows you to obtain and update `global` values. We also recommend optimizing your addon to rely on [`React.memo`](https://react.dev/reference/react/memo), or the following hooks; [`useMemo`](https://react.dev/reference/react/useMemo), [`useCallback`](https://react.dev/reference/react/useCallback) to prevent a high volume of re-render cycles. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useArgs Hook that allows you to retrieve or update a story's [`args`](../writing-stories/args.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - **Learn more about the Storybook addon ecosystem** -* [Types of addons](./addon-types.mdx) for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* [Presets](./writing-presets.mdx) for preset development -* [Integration catalog](./integration-catalog.mdx) for requirements and available recipes -* API reference to learn about the available APIs +- [Types of addons](./addon-types.mdx) for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- [Presets](./writing-presets.mdx) for preset development +- [Integration catalog](./integration-catalog.mdx) for requirements and available recipes +- API reference to learn about the available APIs diff --git a/docs/addons/configure-addons.mdx b/docs/addons/configure-addons.mdx index 72e4d73d5c1f..4751bf2c833d 100644 --- a/docs/addons/configure-addons.mdx +++ b/docs/addons/configure-addons.mdx @@ -1,5 +1,5 @@ --- -title: 'Configure and communicate with an addon' +title: Configure and communicate with an addon sidebar: order: 3 title: Configure addons @@ -11,7 +11,7 @@ The addon API is designed for customization. It offers addon authors different w Presets offload the burden of configuration from the user to the addon. Preset options are global and are accessible from NodeJS. They're ideal for pre-configuring Webpack loaders, Babel plugins, and other library or framework-specific configurations. -For example, many libraries require that the app be wrapped by a `Provider` which *provides* data to components down the tree. Presets can describe behavior like adding wrappers automatically, without users having to do any manual configuration. If a user installs an addon that has Presets, the addon can instruct Storybook to wrap all stories in `Provider`. This allows folks to start using your library with Storybook, with just 1 line of config! +For example, many libraries require that the app be wrapped by a `Provider` which _provides_ data to components down the tree. Presets can describe behavior like adding wrappers automatically, without users having to do any manual configuration. If a user installs an addon that has Presets, the addon can instruct Storybook to wrap all stories in `Provider`. This allows folks to start using your library with Storybook, with just 1 line of config! For more on presets, see: [Write a preset addon](./writing-presets.mdx) diff --git a/docs/addons/index.mdx b/docs/addons/index.mdx index f164e16f0746..f92656eb489a 100644 --- a/docs/addons/index.mdx +++ b/docs/addons/index.mdx @@ -1,5 +1,5 @@ --- -title: 'Introduction to addons' +title: Introduction to addons hideRendererSelector: true sidebar: order: 9 @@ -17,10 +17,10 @@ Before writing your first [addon](https://storybook.js.org/addons), let’s take The **Manager** is the UI responsible for rendering the: -* πŸ” Search -* 🧭 Navigation -* πŸ”— Toolbars -* πŸ“¦ Addons +- πŸ” Search +- 🧭 Navigation +- πŸ”— Toolbars +- πŸ“¦ Addons The **Preview** area is an `iframe` where your stories are rendered. diff --git a/docs/addons/install-addons.mdx b/docs/addons/install-addons.mdx index c4e8f66defcf..2abbc89fdf28 100644 --- a/docs/addons/install-addons.mdx +++ b/docs/addons/install-addons.mdx @@ -1,5 +1,5 @@ --- -title: 'Install addons' +title: Install addons sidebar: order: 1 title: Install @@ -13,14 +13,12 @@ Storybook includes a [`storybook add`](../api/cli-options.mdx#add) command to au Run the `storybook add` command using your chosen package manager, and the CLI will update your Storybook configuration to include the addon and install any necessary dependencies. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - If you're attempting to install multiple addons at once, it will only install the first addon that was specified. This is a known limitation of the current implementation and will be addressed in a future release. + +If you're attempting to install multiple addons at once, it will only install the first addon that was specified. This is a known limitation of the current implementation and will be addressed in a future release. + ### Manual installation @@ -29,20 +27,12 @@ Storybook addons are always added through the [`addons`](../api/main-config/main Run the following command with your package manager of choice to install the addon. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Next, update `.storybook/main.js|ts` to the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - When you run Storybook, the accessibility testing addon will be enabled. ![Storybook addon installed and registered](../_assets/addons/storybook-addon-installed-registered.png) @@ -51,8 +41,4 @@ When you run Storybook, the accessibility testing addon will be enabled. To remove an addon from Storybook, you can choose to manually uninstall it and remove it from the configuration file (i.e., [`.storybook/main.js|ts`](../configure/index.mdx)) or opt-in to do it automatically via the CLI with the [`remove`](../api/cli-options.mdx#remove) command. For example, to remove the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) from Storybook with the CLI, run the following command: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/addons/integration-catalog.mdx b/docs/addons/integration-catalog.mdx index e92266353666..ba3a172ed2f6 100644 --- a/docs/addons/integration-catalog.mdx +++ b/docs/addons/integration-catalog.mdx @@ -1,5 +1,5 @@ --- -title: 'Add to the integration catalog' +title: Add to the integration catalog sidebar: order: 5 title: Add to catalog @@ -13,13 +13,15 @@ Storybook addons are distributed via npm. The catalog is populated by querying n Add your addon to the catalog by publishing a npm package that follows these requirements: -* `package.json` with [module information](./writing-addons.mdx#setup) and [addon metadata](#addon-metadata) -* `README.md` file with installation and configuration instructions -* `/dist` directory containing transpiled ES5 code -* `preset.js` file written as an ES5 module at the root level +- `package.json` with [module information](./writing-addons.mdx#setup) and [addon metadata](#addon-metadata) +- `README.md` file with installation and configuration instructions +- `/dist` directory containing transpiled ES5 code +- `preset.js` file written as an ES5 module at the root level - Get a refresher on how to [write a Storybook addon](./writing-addons.mdx). + +Get a refresher on how to [write a Storybook addon](./writing-addons.mdx). + ### Addon metadata @@ -31,32 +33,34 @@ We rely on metadata to organize your addon in the catalog. You must add the - Make sure to copy each item **exactly** as listed so that we can properly index your addon in our catalog. + +Make sure to copy each item **exactly** as listed so that we can properly index your addon in our catalog. + ```json title="package.json" @@ -103,8 +107,8 @@ If you'd like to request a recipe, open a [new discussion](https://github.com/st **Learn more about the Storybook addon ecosystem** -* [Types of addons](./addon-types.mdx) for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* [Presets](./writing-presets.mdx) for preset development -* Integration catalog for requirements and available recipes -* [API reference](./addons-api.mdx) to learn about the available APIs +- [Types of addons](./addon-types.mdx) for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- [Presets](./writing-presets.mdx) for preset development +- Integration catalog for requirements and available recipes +- [API reference](./addons-api.mdx) to learn about the available APIs diff --git a/docs/addons/writing-addons.mdx b/docs/addons/writing-addons.mdx index 9fe4f23b0e4f..7f0ee73b8d48 100644 --- a/docs/addons/writing-addons.mdx +++ b/docs/addons/writing-addons.mdx @@ -1,5 +1,5 @@ --- -title: 'Write an addon' +title: Write an addon sidebar: order: 2 title: Write @@ -24,14 +24,12 @@ There are two main categories of addons, each with its role: The addon built in this guide is a UI-based addon, specifically a [toolbar](./addon-types.mdx#toolbars) addon, enabling users to draw outlines around each element in the story through a shortcut or click of a button. UI addons can create other types of UI elements, each with its function: [panels](./addon-types.mdx#panels) and [tabs](./addon-types.mdx#tabs), providing users with various ways to interact with the UI. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - + Addons with a UI must use the same React version as Storybook. If your component library uses a different React version, you must use addons that are built and published as standalone packages. We'll cover how to do this with the [Addon Kit](https://github.com/storybookjs/addon-kit). + ## Setup @@ -42,15 +40,13 @@ To create your first addon, you're going to use the [Addon Kit](https://github.c Clone the repository you just created and install its dependencies. When the installation process finishes, you will be prompted with questions to configure your addon. Answer them, and when you're ready to start building your addon, run the following command to start Storybook in development mode and develop your addon in watch mode: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use - JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript. + +The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use +JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript. + ### Understanding the build system @@ -65,12 +61,8 @@ The `tsup` configuration handles these complexities by default, but you can cust By default, code for the UI-based addons is located in one of the following files, depending on the type of addon built: **`src/Tool.tsx`**, **`src/Panel.tsx`**, or **`src/Tab.tsx`**. Since we're building a toolbar addon, we can safely remove the `Panel` and `Tab` files and update the remaining file to the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Going through the code blocks in sequence: ```ts title="src/Tool.tsx" @@ -125,12 +117,8 @@ The `Tool` component is the entry point of the addon. It renders the UI elements Moving onto the manager, here we register the addon with Storybook using a unique name and identifier. Since we've removed the `Panel` and `Tab` files, we'll need to adjust the file to only reference the addon we're building. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Conditionally render the addon Notice the `match` property. It allows you to control the view mode (story or docs) and tab (the story canvas or [custom tabs](./addon-types.mdx#tabs)) where the toolbar addon is visible. For example: @@ -148,28 +136,16 @@ Run the `start` script to build and start Storybook and verify that the addon is In Storybook, applying styles for addons is considered a side-effect. Therefore, we'll need to make some changes to our addon to allow it to use the styles when it is active and remove them when it's disabled. We're going to rely on two of Storybook's features to handle this: [decorators](../writing-stories/decorators.mdx) and [globals](../essentials/toolbars-and-globals.mdx#globals). To handle the CSS logic, we must include some helper functions to inject and remove the stylesheets from the DOM. Start by creating the helper file with the following content: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Next, create the file with the styles we want to inject with the following content: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Since the addon can be active in both the story and documentation modes, the DOM node for Storybook's preview `iframe` is different in these two modes. In fact, Storybook renders multiple story previews on one page when in documentation mode. Therefore, we'll need to choose the correct selector for the DOM node where the styles will be injected and ensure the CSS is scoped to that particular selector. That mechanism is provided as an example within the `src/withGlobals.ts` file, which we'll use to connect the styling and helper functions to the addon logic. Update the file to the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Packaging and publishing Storybook addons, similar to most packages in the JavaScript ecosystem, are distributed as NPM packages. However, they have specific criteria that need to be met to be published to NPM and crawled by the integration catalog: @@ -232,9 +208,11 @@ The second metadata category is related to the [integration catalog](https://sto ``` - The `storybook` configuration element includes additional properties that help customize the - addon's searchability and indexing. For more information, see the [Integration catalog - documentation](./integration-catalog.mdx). + +The `storybook` configuration element includes additional properties that help customize the +addon's searchability and indexing. For more information, see the [Integration catalog +documentation](./integration-catalog.mdx). + One essential item to note is the `keywords` property as it maps to the catalog's tag system. Adding the `storybook-addon` keyword ensures that the addon is discoverable in the catalog when searching for addons. The remaining keywords help with the searchability and categorization of the addon. @@ -261,12 +239,8 @@ npx auto create-labels Finally, run the following command to create a release for your addon. This will build and package the addon code, bump the version, push the release into GitHub and npm, and generate a changelog. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### CI automation By default, the Addon Kit comes pre-configured with a GitHub Actions workflow, enabling you to automate the release management process. This ensures that the package is always up to date with the latest changes and that the changelog is updated accordingly. However, you'll need additional configuration to use your NPM and GitHub tokens to publish the package successfully. In your repository, click the **Settings** tab, then the **Secrets and variables** dropdown, followed by the **Actions** item. You should see the following screen: diff --git a/docs/addons/writing-presets.mdx b/docs/addons/writing-presets.mdx index 9c9896a0ab7d..2c91b1f74b32 100644 --- a/docs/addons/writing-presets.mdx +++ b/docs/addons/writing-presets.mdx @@ -1,5 +1,5 @@ --- -title: 'Write a preset addon' +title: Write a preset addon sidebar: order: 4 title: Write a preset @@ -15,22 +15,14 @@ Preset addons allow developers to compose various configuration options and plug This type of preset allows you to encapsulate and organize configurations specific to the addon, including [builder](../builders/index.mdx) support, [Babel](https://babeljs.io/), or third-party integrations. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Root-level presets This type of preset is user-facing and responsible for registering the addon without any additional configuration from the user by bundling Storybook-related features (e.g., [parameters](../writing-stories/parameters.mdx)) via the [`previewAnnotations`](../api/main-config/main-config-preview-annotations.mdx) and UI related features (e.g., addons) via the `managerEntries` API. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Presets API When writing a preset, you can access a select set of APIs to interact with the Storybook environment, including the supported builders (e.g., Webpack, Vite), the Storybook configuration, and UI. Below are the available APIs you can use when writing a preset addon. @@ -39,14 +31,12 @@ When writing a preset, you can access a select set of APIs to interact with the To customize Storybook's Babel configuration and add support for additional features, you can use the [`babelDefault`](../api/main-config/main-config-babel-default.mdx) API. It will apply the provided configuration ahead of any other user presets, which can be further customized by the end user via the [`babel`](../api/main-config/main-config-babel.mdx) configuration option. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - The Babel configuration is only applied to frameworks that use Babel internally. If you enable it for a framework that uses a different compiler, like [SWC](https://swc.rs/) or [esbuild](https://esbuild.github.io/), it will be ignored. + +The Babel configuration is only applied to frameworks that use Babel internally. If you enable it for a framework that uses a different compiler, like [SWC](https://swc.rs/) or [esbuild](https://esbuild.github.io/), it will be ignored. + ### Builders @@ -57,62 +47,38 @@ By default, Storybook provides support for the leading industry builders, includ If you are creating a preset and want to include Vite support, the `viteFinal` API can be used to modify the default configuration and enable additional features. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - #### Webpack To customize the Webpack configuration in Storybook to add support for additional file types, apply specific loaders, configure plugins, or make any other necessary modifications, you can use the `webpackFinal` API. Once invoked, it will extend the default Webpack configuration with the provided configuration. An example of this would be: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### ManagerEntries If you're writing a preset that loads third-party addons, which you may not have control over, but require access to specific features or additional configuration, you can use the `managerEntries` API. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### PreviewAnnotations If you need additional settings to render stories for a preset, like [decorators](../writing-stories/decorators.mdx) or [parameters](../writing-stories/parameters.mdx), you can use the `previewAnnotations` API. For example, to apply a decorator to all stories, create a preview file that includes the decorator and make it available to the preset as follows: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Advanced configuration The presets API is designed to be flexible and allow you to customize Storybook to your specific needs, including using presets for more advanced use cases without publishing them. In such cases, you can rely on a private preset. These private presets contain configuration options meant for development purposes and not for end-users. The `.storybook/main.js|ts` file is an example of such a private preset that empowers you to modify the behavior and functionality of Storybook. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Addons For addon consumers, the [`managerEntries`](#managerentries) API can be too technical, making it difficult to use. To make it easier to add addons to Storybook, the preset API provides the [`addons`](../api/main-config/main-config-addons.mdx) API, which accepts an array of addon names and will automatically load them for you. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - The array of values supports references to additional presets and addons that should be included in the manager. Storybook will automatically detect whether the provided value is a preset or an addon and load it accordingly. ### Entries @@ -123,20 +89,12 @@ Entries are the place to register entry points for the preview. This feature can The Storybook preset API also provides access to the UI configuration, including the `head` and `body` HTML elements of the preview, configured by the [`previewHead`](../api/main-config/main-config-preview-head.mdx) and [`previewBody`](../api/main-config/main-config-preview-body.mdx) APIs. Both allow you to set up Storybook in a way that is similar to using the [`preview-head.html`](../configure/story-rendering.mdx#adding-to-head) and [`preview-body.html`](../configure/story-rendering.mdx#adding-to-body) files. These methods accept a string and return a modified version, injecting the provided content into the HTML element. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Additionally, if you need to customize the manager (i.e., where Storybook’s search, navigation, toolbars, and addons render), you can use the [`managerHead`](../api/main-config/main-config-manager-head.mdx) to modify the UI, similar to how you would do it with the `manager-head.html` file. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - However, if you need, you can also customize the template used by Storybook to render the UI. To do so, you can use the `previewMainTemplate` API and provide a reference for a custom template created as a `ejs` file. For an example of how to do this, see the [template](https://github.com/storybookjs/storybook/blob/next/code/builders/builder-webpack5/templates/preview.ejs) used by the Webpack 5 builder. ## Troubleshooting @@ -147,8 +105,8 @@ As Storybook relies on [esbuild](https://esbuild.github.io/) instead of Webpack **Learn more about the Storybook addon ecosystem** -* [Types of addons](./addon-types.mdx) for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* Presets for preset development -* [Integration catalog](./integration-catalog.mdx) for requirements and available recipes -* [API reference](./addons-api.mdx) to learn about the available APIs +- [Types of addons](./addon-types.mdx) for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- Presets for preset development +- [Integration catalog](./integration-catalog.mdx) for requirements and available recipes +- [API reference](./addons-api.mdx) to learn about the available APIs diff --git a/docs/ai/best-practices.mdx b/docs/ai/best-practices.mdx index 3143c2d8c303..d350015068a9 100644 --- a/docs/ai/best-practices.mdx +++ b/docs/ai/best-practices.mdx @@ -4,11 +4,13 @@ sidebar: order: 2 title: Best practices --- - + - The best practices here relate to the [generated manifests](./manifests.mdx), which are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +The best practices here relate to the [generated manifests](./manifests.mdx), which are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -77,7 +79,10 @@ For unattached MDX docs pages (such as documentation for design tokens, guidelin ```jsx title="Colors.mdx" import { Meta } from '@storybook/addon-docs/blocks'; - +; ``` ## Docs content @@ -116,7 +121,7 @@ You can also remove an entire component from the manifest, by removing the tag i Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata: -```jsx title="DocForHumansOnly.mdx" +```mdx title="DocForHumansOnly.mdx" import { Meta } from '@storybook/addon-docs/blocks'; @@ -131,5 +136,3 @@ import { Meta } from '@storybook/addon-docs/blocks'; - [MCP server API](./mcp/api.mdx) - [Sharing your MCP server](./mcp/sharing.mdx) - [Manifests](./manifests.mdx) - - diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx index 809e20ad6533..5e6efb14d5ba 100644 --- a/docs/ai/index.mdx +++ b/docs/ai/index.mdx @@ -4,11 +4,13 @@ sidebar: order: 5 title: AI --- - + - While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](./manifests.mdx) and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](./manifests.mdx) and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + diff --git a/docs/ai/manifests.mdx b/docs/ai/manifests.mdx index 685be46d286c..cfce8fc72db3 100644 --- a/docs/ai/manifests.mdx +++ b/docs/ai/manifests.mdx @@ -5,9 +5,11 @@ sidebar: --- - While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the manifests and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the manifests and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -38,11 +40,15 @@ type ButtonProps = { * Button is used for user interactions that do not navigate to another route. * For navigation, use [Link](?path=/docs/link--default) instead. */ -export const Button: React.FC = ({ onClick }) => { /* ... */ }; +export const Button: React.FC = ({ onClick }) => { + //... +}; ``` - Check the [best practices](./best-practices.mdx) guide for tips on writing effective JSDoc comments for your components and other ways to provide helpful context for the agents. + +Check the [best practices](./best-practices.mdx) guide for tips on writing effective JSDoc comments for your components and other ways to provide helpful context for the agents. + The raw JSON components manifest can be accessed at `http://localhost:6006/manifests/components.json` (your port may vary) when your Storybook is running or at the `/manifests/components.json` route in a built Storybook. @@ -51,7 +57,9 @@ The raw JSON components manifest can be accessed at `http://localhost:6006/manif Example components manifest entry - While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + +While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + ```json @@ -74,9 +82,7 @@ The raw JSON components manifest can be accessed at `http://localhost:6006/manif } ], "import": "import { Button } from \"@mealdrop/ui\";", - "jsDocTags": { - - }, + "jsDocTags": {}, "description": "Primary UI component for user interaction", "reactDocgen": { "description": "Primary UI component for user interaction", @@ -217,6 +223,7 @@ The raw JSON components manifest can be accessed at `http://localhost:6006/manif } } ``` +
## Docs (MDX) manifest @@ -226,14 +233,18 @@ The docs manifest is generated from the [MDX files](../writing-docs/mdx.mdx) in The raw JSON docs manifest can be accessed at `http://localhost:6006/manifests/docs.json` (your port may vary) when your Storybook is running or at the `/manifests/docs.json` route in a built Storybook. - Check the [best practices](./best-practices.mdx) guide for tips on writing effective documentation and providing helpful context for the agents. + +Check the [best practices](./best-practices.mdx) guide for tips on writing effective documentation and providing helpful context for the agents. +
Example docs manifest entry - While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + +While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + ```json @@ -249,6 +260,7 @@ The raw JSON docs manifest can be accessed at `http://localhost:6006/manifests/d } } ``` +
## Debugging @@ -269,7 +281,7 @@ You can also remove an entire component from the manifest by removing the tag in Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata: -```jsx title="DocForHumansOnly.mdx" +```mdx title="DocForHumansOnly.mdx" import { Meta } from '@storybook/addon-docs/blocks'; diff --git a/docs/ai/mcp/api.mdx b/docs/ai/mcp/api.mdx index 7d825cab597a..dc94a2efaf0e 100644 --- a/docs/ai/mcp/api.mdx +++ b/docs/ai/mcp/api.mdx @@ -4,11 +4,13 @@ sidebar: order: 2 title: API --- - + - While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -31,7 +33,7 @@ Type: } ``` -Default: +Default: ```ts { diff --git a/docs/ai/mcp/overview.mdx b/docs/ai/mcp/overview.mdx index dab0b2f8a7a4..f487fc94e7d4 100644 --- a/docs/ai/mcp/overview.mdx +++ b/docs/ai/mcp/overview.mdx @@ -6,9 +6,11 @@ sidebar: --- - While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + diff --git a/docs/ai/mcp/sharing.mdx b/docs/ai/mcp/sharing.mdx index 0ec12a48d753..633787a464c7 100644 --- a/docs/ai/mcp/sharing.mdx +++ b/docs/ai/mcp/sharing.mdx @@ -6,9 +6,11 @@ sidebar: --- - While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and [MCP server](./overview.mdx)) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and [MCP server](./overview.mdx)) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -56,11 +58,11 @@ import { createStorybookMcpHandler } from '@storybook/mcp'; const storybookMcpHandler = await createStorybookMcpHandler(); export async function handleRequest(request: Request): Promise { - if (new URL(request.url).pathname === '/mcp') { - return storybookMcpHandler(request); - } + if (new URL(request.url).pathname === '/mcp') { + return storybookMcpHandler(request); + } - return new Response('Not found', { status: 404 }); + return new Response('Not found', { status: 404 }); } ``` diff --git a/docs/api/arg-types.mdx b/docs/api/arg-types.mdx index 9b3dde6cf468..f1cf9053e70f 100644 --- a/docs/api/arg-types.mdx +++ b/docs/api/arg-types.mdx @@ -1,8 +1,7 @@ --- -title: 'ArgTypes' +title: ArgTypes sidebar: order: 3 - title: ArgTypes --- ArgTypes specify the behavior of [args](../writing-stories/args.mdx). By specifying the type of an arg, you constrain the values that it can accept and provide information about args that are not explicitly set (i.e., [description](#description)). @@ -35,28 +34,16 @@ For most Storybook projects, argTypes are [automatically inferred](#automatic-ar ArgTypes are most often specified at the component level, in the [meta (or default export)](../writing-stories/index.mdx#default-export) of the CSF file: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - They can apply to all stories when specified at the project (global) level, in the `preview.js|ts` configuration file: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Or they can apply only to a [specific story](../writing-stories/index.mdx#defining-stories): -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `argTypes` Type: @@ -110,12 +97,8 @@ Default: Specify the behavior of the [controls panel](../essentials/controls.mdx) for the arg. If you specify a string, it's used as the [`type`](#controltype) of the control. If you specify an object, you can provide additional configuration. Specifying `false` will prevent the control from rendering. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - #### `control.type` Type: `ControlType | null` @@ -124,26 +107,28 @@ Default: [Inferred](#automatic-argtype-inference); `'select'`, if [`options`](#o Specifies the type of control used to change the arg value with the [controls panel](../essentials/controls.mdx). Here are the available types, `ControlType`, grouped by the type of data they handle: -| DataΒ type | ControlType | Description | -| -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **array** | `'object'` | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.
`{ control: 'object' }` | -| **boolean** | `'boolean'` | Provides a toggle for switching between possible states.
`{ control: 'boolean' }` | -| **enum** | `'check'` | Provides a set of stacked checkboxes for selecting multiple options.
`{ control: 'check', options: ['email', 'phone', 'mail'] }` | -| | `'inline-check'` | Provides a set of inlined checkboxes for selecting multiple options.
`{ control: 'inline-check', options: ['email', 'phone', 'mail'] }` | -| | `'radio'` | Provides a set of stacked radio buttons based on the available options.
`{ control: 'radio', options: ['email', 'phone', 'mail'] }` | -| | `'inline-radio'` | Provides a set of inlined radio buttons based on the available options.
`{ control: 'inline-radio', options: ['email', 'phone', 'mail'] }` | -| | `'select'` | Provides a select to choose a single value from the options.
`{ control: 'select', options: [20, 30, 40, 50] }` | -| | `'multi-select'` | Provides a select to choose multiple values from the options.
`{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }` | -| **number** | `'number'` | Provides a numeric input to include the range of all possible values.
`{ control: { type: 'number', min:1, max:30, step: 2 } }` | -| | `'range'` | Provides a range slider to include all possible values.
`{ control: { type: 'range', min: 1, max: 30, step: 3 } }` | -| **object** | `'file'` | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.
`{ control: { type: 'file', accept: '.png' } }` | -| | `'object'` | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.
`{ control: 'object' }` | -| **string** | `'color'` | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.
`{ control: { type: 'color', presetColors: ['red', 'green']} }` | -| | `'date'` | Provides a datepicker to choose a date.
`{ control: 'date' }` | -| | `'text'` | Provides a freeform text input.
`{ control: 'text' }` | +| DataΒ type | ControlType | Description | +| ----------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **array** | `'object'` | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.
`{ control: 'object' }` | +| **boolean** | `'boolean'` | Provides a toggle for switching between possible states.
`{ control: 'boolean' }` | +| **enum** | `'check'` | Provides a set of stacked checkboxes for selecting multiple options.
`{ control: 'check', options: ['email', 'phone', 'mail'] }` | +| | `'inline-check'` | Provides a set of inlined checkboxes for selecting multiple options.
`{ control: 'inline-check', options: ['email', 'phone', 'mail'] }` | +| | `'radio'` | Provides a set of stacked radio buttons based on the available options.
`{ control: 'radio', options: ['email', 'phone', 'mail'] }` | +| | `'inline-radio'` | Provides a set of inlined radio buttons based on the available options.
`{ control: 'inline-radio', options: ['email', 'phone', 'mail'] }` | +| | `'select'` | Provides a select to choose a single value from the options.
`{ control: 'select', options: [20, 30, 40, 50] }` | +| | `'multi-select'` | Provides a select to choose multiple values from the options.
`{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }` | +| **number** | `'number'` | Provides a numeric input to include the range of all possible values.
`{ control: { type: 'number', min:1, max:30, step: 2 } }` | +| | `'range'` | Provides a range slider to include all possible values.
`{ control: { type: 'range', min: 1, max: 30, step: 3 } }` | +| **object** | `'file'` | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.
`{ control: { type: 'file', accept: '.png' } }` | +| | `'object'` | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.
`{ control: 'object' }` | +| **string** | `'color'` | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.
`{ control: { type: 'color', presetColors: ['red', 'green']} }` | +| | `'date'` | Provides a datepicker to choose a date.
`{ control: 'date' }` | +| | `'text'` | Provides a freeform text input.
`{ control: 'text' }` | - The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. + +The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. + #### `control.accept` @@ -190,12 +175,8 @@ Default: [Inferred](#automatic-argtype-inference) Describe the arg. (If you intend to describe the type of the arg, you should use [`table.type`](#tabletype), instead.) -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `if` Type: @@ -212,12 +193,8 @@ Type: Conditionally render an argType based on the value of another [arg](../writing-stories/args.mdx) or [global](../essentials/toolbars-and-globals.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `mapping` Type: `{ [key: string]: { [option: string]: any } }` @@ -228,28 +205,22 @@ When dealing with non-primitive values, you'll notice that you'll run into some `mapping` doesn't have to be exhaustive. If the currently selected option is not listed, it's used verbatim. Can be used with [`control.labels`](#labels). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `name` Type: `string` The `argTypes` object uses the name of the arg as the key. By default, that key is used when displaying the argType in Storybook. You can override the displayed name by specifying a `name` property. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed. - For this reason, the `name` property is best used when defining an `argType` that is only used for documentation purposes and not an actual property of the component. For example, when [providing argTypes for each property of an object](https://stackblitz.com/edit/github-uplqzp?file=src/stories/Button.stories.tsx). +Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed. + +For this reason, the `name` property is best used when defining an `argType` that is only used for documentation purposes and not an actual property of the component. For example, when [providing argTypes for each property of an object](https://stackblitz.com/edit/github-uplqzp?file=src/stories/Button.stories.tsx). + ### `options` @@ -260,12 +231,8 @@ Default: [Inferred](#automatic-argtype-inference) If the arg accepts a finite set of values, you can specify them with `options`. If those values are [complex](../essentials/controls.mdx#dealing-with-complex-values), like JSX elements, you can use [`mapping`](#mapping) to map them to string values. You can use [`control.labels`](#labels) to provide custom labels for the options. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `table` Type: @@ -290,12 +257,8 @@ Default: [Inferred](#automatic-argtype-inference) Specify how the arg is documented in the [`ArgTypes` doc block](./doc-blocks/doc-block-argtypes.mdx), [`Controls` doc block](./doc-blocks/doc-block-controls.mdx), and [Controls panel](../essentials/controls.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - #### `table.category` Type: `string` @@ -347,52 +310,53 @@ Type: `'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType` The full type of `SBType` is:
- SBType - - ```ts - interface SBBaseType { - required?: boolean; - raw?: string; - } +SBType - type SBScalarType = SBBaseType & { - name: 'boolean' | 'string' | 'number' | 'function' | 'symbol'; - }; +```ts +interface SBBaseType { + required?: boolean; + raw?: string; +} - type SBArrayType = SBBaseType & { - name: 'array'; - value: SBType; - }; - type SBObjectType = SBBaseType & { - name: 'object'; - value: Record; - }; - type SBEnumType = SBBaseType & { - name: 'enum'; - value: (string | number)[]; - }; - type SBIntersectionType = SBBaseType & { - name: 'intersection'; - value: SBType[]; - }; - type SBUnionType = SBBaseType & { - name: 'union'; - value: SBType[]; - }; - type SBOtherType = SBBaseType & { - name: 'other'; - value: string; - }; +type SBScalarType = SBBaseType & { + name: 'boolean' | 'string' | 'number' | 'function' | 'symbol'; +}; + +type SBArrayType = SBBaseType & { + name: 'array'; + value: SBType; +}; +type SBObjectType = SBBaseType & { + name: 'object'; + value: Record; +}; +type SBEnumType = SBBaseType & { + name: 'enum'; + value: (string | number)[]; +}; +type SBIntersectionType = SBBaseType & { + name: 'intersection'; + value: SBType[]; +}; +type SBUnionType = SBBaseType & { + name: 'union'; + value: SBType[]; +}; +type SBOtherType = SBBaseType & { + name: 'other'; + value: string; +}; + +type SBType = + | SBScalarType + | SBEnumType + | SBArrayType + | SBObjectType + | SBIntersectionType + | SBUnionType + | SBOtherType; +``` - type SBType = - | SBScalarType - | SBEnumType - | SBArrayType - | SBObjectType - | SBIntersectionType - | SBUnionType - | SBOtherType; - ```
Default: [Inferred](#automatic-argtype-inference) @@ -401,12 +365,8 @@ Specifies the semantic type of the argType. When an argType is [inferred](#autom If you only need to specify the documented type, you should use [`table.type`](#tabletype), instead. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `defaultValue` (⛔️ **Deprecated**) @@ -415,8 +375,4 @@ Type: `any` Define the default value of the argType. Deprecated in favor of defining the [`arg`](../writing-stories/args.mdx) value directly. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/cli-options.mdx b/docs/api/cli-options.mdx index ccbd8fa769b4..472bc740860b 100644 --- a/docs/api/cli-options.mdx +++ b/docs/api/cli-options.mdx @@ -1,17 +1,18 @@ --- -title: 'CLI options' +title: CLI options hideRendererSelector: true sidebar: order: 8 - title: CLI options --- The Storybook command line interface (CLI) is the main tool you use to build and develop Storybook. - Storybook collects completely anonymous data to help us improve user experience. Participation is - optional, and you may [opt-out](../configure/telemetry.mdx#how-to-opt-out) if you'd not like to - share any information. + +Storybook collects completely anonymous data to help us improve user experience. Participation is +optional, and you may [opt-out](../configure/telemetry.mdx#how-to-opt-out) if you'd not like to +share any information. + ## CLI commands @@ -19,9 +20,11 @@ The Storybook command line interface (CLI) is the main tool you use to build and All of the following documentation is available in the CLI by running `storybook --help`. - Passing options to these commands works slightly differently if you're using npm instead of Yarn. - You must prefix all of your options with `--`. For example, `npm run storybook build -- -o - ./path/to/build --quiet`. + +Passing options to these commands works slightly differently if you're using npm instead of Yarn. +You must prefix all of your options with `--`. For example, `npm run storybook build -- -o +./path/to/build --quiet`. + ### `dev` @@ -42,7 +45,7 @@ Options include: | `--exact-port` | Attempts to run Storybook on the exact port number specified.
If the port is already in use, Storybook will exit with an error message.
`storybook dev -p 9009 --exact-port` | | `-h`, `--host [string]` | Host to run Storybook.
`storybook dev -h my-host.com` | | `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook dev -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook dev --loglevel warn` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook dev --loglevel warn` | | `--https` | Serve Storybook over HTTPS. Note: You must provide your own certificate information.
`storybook dev --https` | | `--ssl-ca` | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)
`storybook dev --ssl-ca my-certificate` | | `--ssl-cert` | Provide an SSL certificate. (Required with --https)
`storybook dev --ssl-cert my-ssl-certificate` | @@ -64,9 +67,11 @@ Options include: | `--preview-only` | Skips Storybook's manager from building and opens the app in "preview only" mode, which is designed to be used in [unsupported browsers](../sharing/publish-storybook.mdx#build-storybook-for-older-browsers).
`storybook dev --preview-only` | - With the release of Storybook 8, the `-s` CLI flag was removed. We recommend using the [static - directory](../configure/integration/images-and-assets.mdx#serving-static-files-via-storybook) - instead if you need to serve static files. + +With the release of Storybook 8, the `-s` CLI flag was removed. We recommend using the [static +directory](../configure/integration/images-and-assets.mdx#serving-static-files-via-storybook) +instead if you need to serve static files. + ### `build` @@ -85,7 +90,7 @@ Options include: | `-V`, `--version` | Output the version number.
`storybook build -V` | | `-o`, `--output-dir [dir-name]` | Directory where to store built files.
`storybook build -o /my-deployed-storybook` | | `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook build -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.
`storybook build --loglevel warn` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.
`storybook build --loglevel warn` | | `--quiet` | Suppress verbose build output.
`storybook build --quiet` | | `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook build --debug` | | `--debug-webpack` | Display final webpack configurations for debugging purposes.
`storybook build --debug-webpack` | @@ -101,8 +106,10 @@ Options include: ### `init` - We recommend [`create-storybook`](#create-storybook) for new projects. The `init` command will - remain available for backwards compatibility. + +We recommend [`create-storybook`](#create-storybook) for new projects. The `init` command will +remain available for backwards compatibility. + Installs and initializes the specified version (e.g., `@latest`, `@8`, `@next`) of Storybook into your project. If no version is specified, the latest version is installed. Read more in the [installation guide](../get-started/install.mdx). @@ -123,7 +130,7 @@ Options include: | `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually.
`storybook init --skip-install` | | `-t`, `--type` | Defines the [framework](../configure/integration/frameworks.mdx) to use for your Storybook instance.
`storybook init --type solid` | | `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version, including all features.
`storybook init --yes` | -| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated.
`storybook init --features docs test a11y` | +| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated.
`storybook init --features docs test a11y` | | `--package-manager` | Sets the package manager to use when installing Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook init --package-manager pnpm` | | `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager.
`storybook init --use-pnp` | | `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).
Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.
`storybook init --parser tsx` | @@ -131,7 +138,7 @@ Options include: | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook init --disable-telemetry` | | `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook init --enable-crash-reports` | | `--loglevel ` | Controls level of logging during initialization.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook init --loglevel debug` | -| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | | `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server.
`storybook init --no-dev` | ### `add` @@ -144,15 +151,15 @@ storybook add [addon] [options] Options include: -| Option | Description | -| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information.
`storybook add --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | -| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook add [addon] --package-manager pnpm` | -| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself.
`storybook add [addon] --skip-postinstall` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook add --debug` | -| `--loglevel ` | Controls level of logging during addon installation.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook add [addon] --loglevel debug` | -| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook add [addon] --logfile /tmp/debug-storybook.log` | +| Option | Description | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information.
`storybook add --help` | +| `-c`, `--config-dir` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | +| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook add [addon] --package-manager pnpm` | +| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself.
`storybook add [addon] --skip-postinstall` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook add --debug` | +| `--loglevel ` | Controls level of logging during addon installation.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook add [addon] --loglevel debug` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook add [addon] --logfile /tmp/debug-storybook.log` | ### `remove` @@ -184,20 +191,20 @@ For example, `storybook@latest upgrade --dry-run` will perform a dry run (no act Options include: -| Option | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information.
`storybook upgrade --help` | -| `-c, --config-dir ` | Directory or directories to find Storybook configurations
`storybook upgrade --config-dir .storybook` | -| `-n`, `--dry-run` | Checks for version upgrades without installing them.
`storybook upgrade --dry-run` | -| `-s`, `--skip-check` | Skips the migration check step during the upgrade process.
`storybook upgrade --skip-check` | -| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version.
`storybook upgrade --yes` | -| `-f`,`--force` | Force the upgrade, skipping autoblockers check.
`storybook upgrade --force` | -| `--package-manager` | Sets the package manager to use when upgrading Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook upgrade --package-manager pnpm` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook upgrade --debug` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook upgrade --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook upgrade --enable-crash-reports` | -| `-logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook upgrade --logfile /tmp/debug-storybook.log` | -| `--loglevel ` | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`).
`storybook upgrade --loglevel debug` | +| Option | Description | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information.
`storybook upgrade --help` | +| `-c, --config-dir ` | Directory or directories to find Storybook configurations
`storybook upgrade --config-dir .storybook` | +| `-n`, `--dry-run` | Checks for version upgrades without installing them.
`storybook upgrade --dry-run` | +| `-s`, `--skip-check` | Skips the migration check step during the upgrade process.
`storybook upgrade --skip-check` | +| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version.
`storybook upgrade --yes` | +| `-f`,`--force` | Force the upgrade, skipping autoblockers check.
`storybook upgrade --force` | +| `--package-manager` | Sets the package manager to use when upgrading Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook upgrade --package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook upgrade --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook upgrade --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook upgrade --enable-crash-reports` | +| `-logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook upgrade --logfile /tmp/debug-storybook.log` | +| `--loglevel ` | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`).
`storybook upgrade --loglevel debug` | ### `migrate` @@ -208,9 +215,11 @@ storybook[@version] migrate [codemod] [options] ``` - The command requires the codemod name (e.g., `csf-2-to-3`) as an argument to apply the necessary - changes to your project. You can find the list of available codemods by running `storybook migrate - --list`. + +The command requires the codemod name (e.g., `csf-2-to-3`) as an argument to apply the necessary +changes to your project. You can find the list of available codemods by running `storybook migrate +--list`. + For example, `storybook@latest migrate csf-2-to-3 --dry-run`, checks your project to verify if the codemod can be applied without making any changes, providing you with a report of which files would be affected. @@ -220,7 +229,7 @@ Options include: | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `-h`, `--help` | Output usage information.
`storybook migrate --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | +| `-c`, `--config-dir` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | | `-n`, `--dry-run` | Verify the migration exists and show the files to which it will be applied.
`storybook migrate --dry-run` | | `-l`, `--list` | Shows a list of available codemods.
`storybook migrate --list` | | `-g`, `--glob` | Glob for files upon which to apply the codemods.
`storybook migrate --glob src/**/*.stories.tsx` | @@ -243,7 +252,7 @@ Options include: | Option | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-h`, `--help` | Output usage information.
`storybook automigrate --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook automigrate --config-dir .storybook` | +| `-c`, `--config-dir` | Storybook configuration directory.
`storybook automigrate --config-dir .storybook` | | `-n`, `--dry-run` | Checks for available migrations without applying them.
`storybook automigrate --dry-run` | | `-s`, `--skip-install` | Skip installing dependencies whenever applicable.
`storybook automigrate --skip-install` | | `-y`, `--yes` | Applies available migrations automatically without prompting for confirmation.
`storybook automigrate --yes` | @@ -267,7 +276,7 @@ Options include: | Option | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-h`, `--help` | Output usage information.
`storybook doctor --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook doctor --config-dir .storybook` | +| `-c`, `--config-dir` | Storybook configuration directory.
`storybook doctor --config-dir .storybook` | | `--package-manager` | Sets the package manager to use when running the health check.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook doctor --package-manager pnpm` | | `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook doctor --debug` | @@ -315,7 +324,7 @@ Options include: | Option | Description | | --------------------------------- | ------------------------------------------------------ | | `-o`, `--output-file ` | JSON file to output index | -| `-c`, `--config-dir ` | Storybook configuration directory | +| `-c`, `--config-dir ` | Storybook configuration directory | | `--quiet` | Suppress verbose build output | | `--loglevel ` | Control level of logging during build | | `--disable-telemetry` | Disables Storybook's telemetry | @@ -346,8 +355,10 @@ Options include: | `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook sandbox --enable-crash-reports` | - If you're looking for a hosted version of the available sandboxes, see - [storybook.new](https://storybook.new). + +If you're looking for a hosted version of the available sandboxes, see +[storybook.new](https://storybook.new). + ## `create-storybook` @@ -378,5 +389,5 @@ Options include: | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`create storybook --disable-telemetry` | | `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`create storybook --enable-crash-reports` | | `--loglevel ` | Controls level of logging during initialization.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook init --loglevel debug` | -| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | | `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server.
`create storybook --no-dev` | diff --git a/docs/api/csf/csf-next.mdx b/docs/api/csf/csf-next.mdx index 46b4f470e53e..61530d19a275 100644 --- a/docs/api/csf/csf-next.mdx +++ b/docs/api/csf/csf-next.mdx @@ -1,5 +1,5 @@ --- -title: 'Component Story Format (CSF)' +title: Component Story Format (CSF) isTab: true tab: order: 2 @@ -9,7 +9,9 @@ tab: - CSF Next is currently only supported in [React](?renderer=react), [Vue](?renderer=vue), [Angular](?renderer=angular), and [Web Components](?renderer=web-components) projects. + +CSF Next is currently only supported in [React](?renderer=react), [Vue](?renderer=vue), [Angular](?renderer=angular), and [Web Components](?renderer=web-components) projects. + @@ -17,7 +19,9 @@ tab: - This is a [**preview**](../../releases/features.mdx#preview) feature and (though unlikely) the API may change in future releases. We [welcome feedback](https://github.com/storybookjs/storybook/discussions/30112) and contributions to help improve this feature. + +This is a [**preview**](../../releases/features.mdx#preview) feature and (though unlikely) the API may change in future releases. We [welcome feedback](https://github.com/storybookjs/storybook/discussions/30112) and contributions to help improve this feature. + CSF Next is the next evolution of Storybook's Component Story Format (CSF). This new API uses a pattern called factory functions to provide full type safety to your Storybook stories, making it easier to configure addons correctly and unlocking the full potential of Storybook's features. @@ -69,7 +73,9 @@ export default definePreview({ ``` - The preview configuration will be automatically updated to reference the [necessary addons](#preview-addons) when installing an addon via `npx storybook add ` or running `storybook dev`. + +The preview configuration will be automatically updated to reference the [necessary addons](#preview-addons) when installing an addon via `npx storybook add ` or running `storybook dev`. + ### `preview.meta` @@ -86,7 +92,7 @@ const meta = preview.meta({ parameters: { // type-safe! layout: 'centered', - } + }, }); ``` @@ -114,8 +120,8 @@ To configure subpath imports, add the following to your `package.json`: ```json title="package.json" { "imports": { - "#*": ["./*", "./*.ts", "./*.tsx"], - }, + "#*": ["./*", "./*.ts", "./*.tsx"] + } } ``` @@ -147,7 +153,11 @@ type CustomProps = React.ComponentProps & { customProp: string }; const meta = preview.type<{ args: CustomProps }>().meta({ component: Button, // πŸ‘‡ Correct types - render: ({ customProp, ...args }) => <>{customProp} ; ``` -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - {/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Description } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; {/* Shows the description for the default export (the meta). - If that didn't have any comments, it would show the - comments from the component instead */} +If that didn't have any comments, it would show the +comments from the component instead */} {/* Shows the description for the Primary export */} ``` - {/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-icongallery.mdx b/docs/api/doc-blocks/doc-block-icongallery.mdx index 533bdede03d4..246f2064f887 100644 --- a/docs/api/doc-blocks/doc-block-icongallery.mdx +++ b/docs/api/doc-blocks/doc-block-icongallery.mdx @@ -1,8 +1,7 @@ --- -title: 'IconGallery' +title: IconGallery sidebar: order: 6 - title: IconGallery --- The `IconGallery` block enables you to easily document React icon components associated with your project, displayed in a neat grid. @@ -13,8 +12,6 @@ The `IconGallery` block enables you to easily document React icon components ass To document a set of icons, use the `IconGallery` block to display them in a grid. Each icon is wrapped in an `IconItem` block, enabling you to specify its properties, such as the name and the icon itself. -{/* prettier-ignore-start */} - ```md title="Iconography.mdx" import { Meta, IconGallery, IconItem } from '@storybook/addon-docs/blocks'; @@ -58,15 +55,11 @@ import { Icon as IconExample } from './Icon'; ``` -{/* prettier-ignore-end */} - ### Automate icon documentation If you're working on a project that contains a large number of icons that you want to document, you can extend the `IconGallery` block, wrap `IconItem` in a loop, and iterate over the icons you want to document, including their properties. For example: -{/* prettier-ignore-start */} - -```md title="Iconography.mdx" +```mdx title="Iconography.mdx" import { Meta, IconGallery, IconItem } from '@storybook/addon-docs/blocks'; import { Icon as IconExample } from './Icon'; @@ -83,8 +76,6 @@ import * as icons from './icons'; ``` -{/* prettier-ignore-end */} - ## IconGallery ```js diff --git a/docs/api/doc-blocks/doc-block-markdown.mdx b/docs/api/doc-blocks/doc-block-markdown.mdx index 8d34cadc9325..851cca99eabd 100644 --- a/docs/api/doc-blocks/doc-block-markdown.mdx +++ b/docs/api/doc-blocks/doc-block-markdown.mdx @@ -1,8 +1,7 @@ --- -title: 'Markdown' +title: Markdown sidebar: order: 7 - title: Markdown --- The `Markdown`Β block allows you to import and include plain markdown in your MDX files. @@ -11,22 +10,16 @@ The `Markdown`Β block allows you to import and include plain markdown in your MD When importing markdown files, it’s important to use the `?raw` suffix on the import path to ensure the content is imported as-is, and isn’t being evaluated: -{/* prettier-ignore-start */} - ````md title="README.md" # Button Primary UI component for user interaction ```js -import { Button } from "@storybook/design-system"; +import { Button } from '@storybook/design-system'; ``` ```` -{/* prettier-ignore-end */} - -{/* prettier-ignore-start */} - ```md title="Header.mdx" // DON'T do this, will error import ReadMe from './README.md'; @@ -35,13 +28,11 @@ import ReadMe from './README.md?raw'; import { Markdown } from '@storybook/addon-docs/blocks'; -# A header +# A header {ReadMe} ``` -{/* prettier-ignore-end */} - ## Markdown ```js @@ -64,24 +55,18 @@ Specifies the options passed to the underlying [`markdown-to-jsx` library](https From a purely technical standpoint, we could include the imported markdown directly in the MDX file like this: -{/* prettier-ignore-start */} - -```md +```mdx {/* THIS WON'T WORK, THIS IS TO DEMONSTRATE AN ERROR */} import ReadMe from './README.md'; -# A header +# A header {ReadMe} ``` -{/* prettier-ignore-end */} - However, there are small syntactical differences between plain markdown and MDX2. MDX2 is more strict and will interpret certain content as JSX expressions. Here’s an example of a perfectly valid markdown file, that would break if it was handled directly by MDX2: -{/* prettier-ignore-start */} - ```md # A header @@ -90,12 +75,8 @@ However, there are small syntactical differences between plain markdown and MDX2 ``` -{/* prettier-ignore-end */} - Furthermore, MDX2 wraps all strings on newlines in `p` tags or similar, meaning that content would render differently between a plain `.md` file and an `.mdx` file. -{/* prettier-ignore-start */} - ```md # A header @@ -111,5 +92,3 @@ The example above will remain as-is in plain markdown, but MDX2 will compile it

Some text

``` - -{/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-meta.mdx b/docs/api/doc-blocks/doc-block-meta.mdx index cf686e569941..39812947df3f 100644 --- a/docs/api/doc-blocks/doc-block-meta.mdx +++ b/docs/api/doc-blocks/doc-block-meta.mdx @@ -1,28 +1,25 @@ --- -title: 'Meta' +title: Meta sidebar: order: 8 - title: Meta --- The `Meta` block is used to [attach](#attached-vs-unattached) a custom MDX docs page alongside a component’s list of stories. It doesn’t render any content, but serves two purposes in an MDX file: -* Attaches the MDX file to a component and its stories, or -* Controls the location of the unattached docs entry in the sidebar. +- Attaches the MDX file to a component and its stories, or +- Controls the location of the unattached docs entry in the sidebar. -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - - The Meta block doesn’t render anything visible. + +The Meta block doesn’t render anything visible. + ## Meta @@ -45,35 +42,28 @@ Type: `string` Sets the name of the [attached](#attached-vs-unattached) doc entry. You can attach more than one MDX file to the same component in the sidebar by setting different names for each file's `Meta`. -{/* prettier-ignore-start */} - -```md title="Component.mdx" +```mdx title="Component.mdx" import { Meta } from '@storybook/addon-docs/blocks'; import * as ComponentStories from './component.stories'; {/* This MDX file is now called "Special Docs" */} + ``` -{/* prettier-ignore-end */} - ### `of` Type: CSF file exports Specifies which CSF file is [attached](#attached-vs-unattached) to this MDX file. Pass the **full set of exports** from the CSF file (not the default export!). -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - Attaching an MDX file to a component’s stories with the `of` prop serves two purposes: 1. Ensures the MDX content appears in the sidebar inside the component’s story list. By default, it will be named whatever the `docs.defaultName` (which defaults to `"Docs"`) option is set to in `main.js`. But this can be overridden with the [`name` prop](#name). @@ -81,7 +71,7 @@ Attaching an MDX file to a component’s stories with the `of` prop serves two p - The `of` prop is optional. If you don’t want to attach a specific CSF file to this MDX file, you can either use the `title` prop to control the location, or emit `Meta` entirely, and let [autotitle](../../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) decide where it goes. +The `of` prop is optional. If you don’t want to attach a specific CSF file to this MDX file, you can either use the `title` prop to control the location, or emit `Meta` entirely, and let [autotitle](../../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) decide where it goes. @@ -92,22 +82,18 @@ Type: `string` Sets the title of an [unattached](#attached-vs-unattached) MDX file. {/* prettier-ignore-start */} - -```md -{/* Introduction.mdx */} - +```mdx title="Introduction.mdx" import { Meta } from '@storybook/addon-docs/blocks'; {/* Override the docs entry's location in the sidebar with title */} ``` - {/* prettier-ignore-end */} - If you want to change the sorting of the docs entry with the component’s stories, use [Story Sorting](../../writing-stories/naming-components-and-hierarchy.mdx#sorting-stories), or add specific MDX files to your `stories` field in `main.js` in order. - +If you want to change the sorting of the docs entry with the component’s stories, use [Story Sorting](../../writing-stories/naming-components-and-hierarchy.mdx#sorting-stories), or add specific MDX files to your `stories` field in `main.js` in order. + ## Attached vs. unattached diff --git a/docs/api/doc-blocks/doc-block-primary.mdx b/docs/api/doc-blocks/doc-block-primary.mdx index 0179811d4bc1..2c6b72e4833f 100644 --- a/docs/api/doc-blocks/doc-block-primary.mdx +++ b/docs/api/doc-blocks/doc-block-primary.mdx @@ -1,17 +1,14 @@ --- -title: 'Primary' +title: Primary sidebar: order: 9 - title: Primary --- The `Primary` block displays the primary (first defined in the stories file) story, in a [`Story`](./doc-block-story.mdx) block. It is typically rendered immediately under the title in a docs entry. ![Screenshot of Primary block](../../_assets/api/doc-block-primary.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Primary } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -20,8 +17,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Primary ```js diff --git a/docs/api/doc-blocks/doc-block-source.mdx b/docs/api/doc-blocks/doc-block-source.mdx index 782e26fe114d..0de6bb507aff 100644 --- a/docs/api/doc-blocks/doc-block-source.mdx +++ b/docs/api/doc-blocks/doc-block-source.mdx @@ -1,17 +1,14 @@ --- -title: 'Source' +title: Source sidebar: order: 10 - title: Source --- The `Source` block is used to render a snippet of source code directly. ![Screenshot of Source block](../../_assets/api/doc-block-source.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Source } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -20,8 +17,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Source ```js @@ -29,27 +24,20 @@ import { Source } from '@storybook/addon-docs/blocks'; ```
- Configuring with props and parameters - - ℹ️ Like most blocks, the `Source` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.source`. +Configuring with props and parameters - The following `language` configurations are equivalent: +ℹ️ Like most blocks, the `Source` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.source`. - {/* prettier-ignore-start */} +The following `language` configurations are equivalent: - + - {/* prettier-ignore-end */} - - {/* prettier-ignore-start */} - - ```md title="ButtonDocs.mdx" - - ``` +```md title="ButtonDocs.mdx" + +``` - {/* prettier-ignore-end */} +The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level. - The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level.
### `code` @@ -60,22 +48,20 @@ Default: `parameters.docs.source.code` Provides the source code to be rendered. -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Source } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; - +}`} +/> ``` -{/* prettier-ignore-end */} - ### `dark` Type: `boolean` @@ -86,30 +72,30 @@ Determines if the snippet is rendered in dark mode. - Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](./doc-block-canvas.mdx)β€”like it is in [autodocs](../../writing-docs/autodocs.mdx)β€”it will always use dark mode. +Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](./doc-block-canvas.mdx)β€”like it is in [autodocs](../../writing-docs/autodocs.mdx)β€”it will always use dark mode. - - ### `excludeDecorators` + + +### `excludeDecorators` - Type: `boolean` +Type: `boolean` + +Default: `parameters.docs.source.excludeDecorators` - Default: `parameters.docs.source.excludeDecorators` +Determines if [decorators](../../writing-stories/decorators.mdx) are rendered in the source code snippet. - Determines if [decorators](../../writing-stories/decorators.mdx) are rendered in the source code snippet. - + ### `language` Type: {/* prettier-ignore-start */} - ```ts 'jsextra' | 'jsx' | 'json' | 'yml' | 'md' | 'bash' | 'css' | 'html' | 'tsx' | 'typescript' | 'graphql' ``` - {/* prettier-ignore-end */} Default: `parameters.docs.source.language` or `'jsx'` @@ -143,12 +129,12 @@ Default: `parameters.docs.source.type` or `'auto'` Specifies how the source code is rendered. -* **auto**: Same as **dynamic**, if the story's `render` function accepts args inputs and **dynamic** is supported by the framework in use; otherwise same as **code** -* **code**: Renders the value of [`code` prop](#code), otherwise renders static story source -* **dynamic**: Renders the story source with dynamically updated arg values +- **auto**: Same as **dynamic**, if the story's `render` function accepts args inputs and **dynamic** is supported by the framework in use; otherwise same as **code** +- **code**: Renders the value of [`code` prop](#code), otherwise renders static story source +- **dynamic**: Renders the story source with dynamically updated arg values - Note that dynamic snippets will only work if the story uses [`args`](../../writing-stories/args.mdx) and the [`Story` block](./doc-block-story.mdx) for that story is rendered along with the `Source` block. - +Note that dynamic snippets will only work if the story uses [`args`](../../writing-stories/args.mdx) and the [`Story` block](./doc-block-story.mdx) for that story is rendered along with the `Source` block. + diff --git a/docs/api/doc-blocks/doc-block-stories.mdx b/docs/api/doc-blocks/doc-block-stories.mdx index 27916a1ec2ee..c1a24775d251 100644 --- a/docs/api/doc-blocks/doc-block-stories.mdx +++ b/docs/api/doc-blocks/doc-block-stories.mdx @@ -1,17 +1,14 @@ --- -title: 'Stories' +title: Stories sidebar: order: 11 - title: Stories --- The `Stories` block renders the full collection of stories in a stories file. ![Screenshot of Stories block](../../_assets/api/doc-block-stories.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Stories } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -20,8 +17,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Stories ```js @@ -40,8 +35,8 @@ Determines if the collection of stories includes the primary (first) story. - If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation. - +If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation. + ### `title` diff --git a/docs/api/doc-blocks/doc-block-story.mdx b/docs/api/doc-blocks/doc-block-story.mdx index d4822d9e223b..35b8701cd9c4 100644 --- a/docs/api/doc-blocks/doc-block-story.mdx +++ b/docs/api/doc-blocks/doc-block-story.mdx @@ -1,8 +1,7 @@ --- -title: 'Story' +title: Story sidebar: order: 12 - title: Story --- [Stories](../../writing-stories/index.mdx) are Storybook's fundamental building blocks. @@ -11,15 +10,13 @@ In Storybook Docs, you can render any of your stories from your CSF files in the - Typically you want to use the [`Canvas` block](./doc-block-canvas.mdx) to render a story with a surrounding border and the source block, but you can use the `Story` block to render just the story. - +Typically you want to use the [`Canvas` block](./doc-block-canvas.mdx) to render a story with a surrounding border and the source block, but you can use the `Story` block to render just the story. + ![Screenshot of Story block](../../_assets/api/doc-block-story.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx"+ +```mdx title="ButtonDocs.mdx" import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -28,8 +25,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Story ```js @@ -37,27 +32,20 @@ import { Story } from '@storybook/addon-docs/blocks'; ```
- Configuring with props and parameters +Configuring with props and parameters - ℹ️ Like most blocks, the `Story` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.story`. +ℹ️ Like most blocks, the `Story` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.story`. - The following `autoplay` configurations are equivalent: +The following `autoplay` configurations are equivalent: - {/* prettier-ignore-start */} + - - - {/* prettier-ignore-end */} - - {/* prettier-ignore-start */} - - ```md title="ButtonDocs.mdx" - - ``` +```md title="ButtonDocs.mdx" + +``` - {/* prettier-ignore-end */} +The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level. - The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level.
### `autoplay` @@ -73,7 +61,9 @@ Because all stories render simultaneously in docs entries, play functions can pe However, if you know your play function is β€œsafe” to run in docs, you can use this prop to run it automatically. - If a story uses [`mount` in its play function](../../writing-tests/interaction-testing.mdx#run-code-before-the-component-gets-rendered), it will not render in docs unless `autoplay` is set to `true`. + +If a story uses [`mount` in its play function](../../writing-tests/interaction-testing.mdx#run-code-before-the-component-gets-rendered), it will not render in docs unless `autoplay` is set to `true`. + ### `height` @@ -94,8 +84,8 @@ Determines whether the story is rendered `inline` (in the same browser frame as - Setting the `inline` option to false will prevent the associated [controls](./doc-block-controls.mdx) from updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release. - +Setting the `inline` option to false will prevent the associated [controls](./doc-block-controls.mdx) from updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release. + ### `meta` @@ -107,8 +97,7 @@ Specifies the CSF file to which the story is associated. You can render a story from a CSF file that you haven’t attached to the MDX file (via `Meta`) by using the `meta` prop. Pass the **full set of exports** from the CSF file (not the default export!). {/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; import * as HeaderStories from './Header.stories'; @@ -116,10 +105,9 @@ import * as HeaderStories from './Header.stories'; {/* Although this MDX file is largely concerned with Button, - it can render Header stories too */} +it can render Header stories too */} ``` - {/* prettier-ignore-end */} ### `of` @@ -127,4 +115,3 @@ import * as HeaderStories from './Header.stories'; Type: Story export Specifies which story is rendered by the `Story` block. If no `of` is defined and the MDX file is [attached](./doc-block-meta.mdx#attached-vs-unattached), the primary (first) story will be rendered. - diff --git a/docs/api/doc-blocks/doc-block-subtitle.mdx b/docs/api/doc-blocks/doc-block-subtitle.mdx index afe93fa17e28..93292df5cc67 100644 --- a/docs/api/doc-blocks/doc-block-subtitle.mdx +++ b/docs/api/doc-blocks/doc-block-subtitle.mdx @@ -1,24 +1,19 @@ --- -title: 'Subtitle' +title: Subtitle sidebar: order: 13 - title: Subtitle --- The `Subtitle` block can serve as a secondary heading for your docs entry. ![Screenshot of Subtitle block](../../_assets/api/doc-block-title-subtitle-description.png) -{/* prettier-ignore-start */} - ```md title="ButtonDocs.mdx" import { Subtitle } from '@storybook/addon-docs/blocks'; This is the subtitle ``` -{/* prettier-ignore-end */} - ## Subtitle ```js diff --git a/docs/api/doc-blocks/doc-block-tableofcontents.mdx b/docs/api/doc-blocks/doc-block-tableofcontents.mdx index 96b282affee7..d32d9b3a55d8 100644 --- a/docs/api/doc-blocks/doc-block-tableofcontents.mdx +++ b/docs/api/doc-blocks/doc-block-tableofcontents.mdx @@ -1,8 +1,7 @@ --- -title: 'TableOfContents' +title: TableOfContents sidebar: order: 14 - title: TableOfContents --- The `TableOfContents` block renders a table of contents for the current documentation page, allowing users to navigate between sections quickly. It appears as a fixed sidebar on the right side of the documentation page and is hidden on smaller screens (below 768px). @@ -11,7 +10,7 @@ The table of contents is enabled and configured via the `docs.toc` [parameter](. - For a step-by-step guide on enabling and customizing the table of contents, see the [Generate a table of contents](../../writing-docs/autodocs.mdx#generate-a-table-of-contents) section in the Autodocs documentation. +For a step-by-step guide on enabling and customizing the table of contents, see the [Generate a table of contents](../../writing-docs/autodocs.mdx#generate-a-table-of-contents) section in the Autodocs documentation. @@ -19,20 +18,12 @@ The table of contents is enabled and configured via the `docs.toc` [parameter](. Enable the table of contents globally in your Storybook preview configuration: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - You can also enable or disable it for specific components in their stories file: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `toc` parameter options The `docs.toc` parameter accepts either `true` (to enable with defaults) or an object with the following properties: @@ -83,8 +74,4 @@ Type: `object` Provides additional configuration options passed directly to the underlying [`Tocbot`](https://tscanlin.github.io/tocbot/) library. These options are not guaranteed to remain available in future versions of Storybook. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-title.mdx b/docs/api/doc-blocks/doc-block-title.mdx index 1c40d97e7499..9ee82798da35 100644 --- a/docs/api/doc-blocks/doc-block-title.mdx +++ b/docs/api/doc-blocks/doc-block-title.mdx @@ -1,24 +1,19 @@ --- -title: 'Title' +title: Title sidebar: order: 15 - title: Title --- The `Title` block serves as the primary heading for your docs entry. It is typically used to provide the component or page name. ![Screenshot of Title block](../../_assets/api/doc-block-title-subtitle-description.png) -{/* prettier-ignore-start */} - ```md title="ButtonDocs.mdx" import { Title } from '@storybook/addon-docs/blocks'; This is the title ``` -{/* prettier-ignore-end */} - ## Title ```js diff --git a/docs/api/doc-blocks/doc-block-typeset.mdx b/docs/api/doc-blocks/doc-block-typeset.mdx index f7c49b5dabe6..f0ff6ced081a 100644 --- a/docs/api/doc-blocks/doc-block-typeset.mdx +++ b/docs/api/doc-blocks/doc-block-typeset.mdx @@ -1,42 +1,39 @@ --- -title: 'Typeset' +title: Typeset sidebar: order: 16 - title: Typeset --- The `Typeset` block helps document the fonts used throughout your project. ![Screenshot of Typeset block](../../_assets/api/doc-block-typeset.png) -{/* prettier-ignore-start */} - ```md title="Typography.mdx" import { Meta, Typeset } from '@storybook/addon-docs/blocks'; export const typography = { - type: { - primary: '"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif', - }, - weight: { - regular: '400', - bold: '700', - extrabold: '800', - black: '900', - }, - size: { - s1: 12, - s2: 14, - s3: 16, - m1: 20, - m2: 24, - m3: 28, - l1: 32, - l2: 40, - l3: 48, - }, +type: { +primary: '"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif', +}, +weight: { +regular: '400', +bold: '700', +extrabold: '800', +black: '900', +}, +size: { +s1: 12, +s2: 14, +s3: 16, +m1: 20, +m2: 24, +m3: 28, +l1: 32, +l2: 40, +l3: 48, +}, }; export const SampleText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'; @@ -48,20 +45,20 @@ export const SampleText = 'Lorem ipsum dolor sit amet, consectetur adipiscing el **Weights:** 400(regular), 700(bold), 800(extrabold), 900(black) ``` diff --git a/docs/api/doc-blocks/doc-block-unstyled.mdx b/docs/api/doc-blocks/doc-block-unstyled.mdx index addc5f677448..87e9369352fe 100644 --- a/docs/api/doc-blocks/doc-block-unstyled.mdx +++ b/docs/api/doc-blocks/doc-block-unstyled.mdx @@ -1,16 +1,13 @@ --- -title: 'Unstyled' +title: Unstyled sidebar: order: 17 - title: Unstyled --- The `Unstyled` block is a special block that disables Storybook's default styling in MDX docs wherever it is added. By default, most elements (like `h1`, `p`, etc.) in docs have a few default styles applied to ensure the docs look good. However, sometimes you might want some of your content to not have these styles applied. In those cases, wrap the content with the `Unstyled` block to remove the default styles. -{/* prettier-ignore-start */} - ```md title="ButtonDocs.mdx" import { Meta, Unstyled } from "@storybook/addon-docs/blocks"; import { Header } from "./Header.tsx"; @@ -24,7 +21,7 @@ import { Header } from "./Header.tsx"; > This block quote will not be styled - ... neither will this paragraph, nor the following component (which contains an \): +... neither will this paragraph, nor the following component (which contains an \):
@@ -39,24 +36,22 @@ Yields: - The other blocks like [`Story`](./doc-block-story.mdx) and [`Canvas`](./doc-block-canvas.mdx) are already unstyled, so there’s no need to wrap those in the `Unstyled` block to ensure that Storybook’s styles don’t bleed into the stories. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block. - +The other blocks like [`Story`](./doc-block-story.mdx) and [`Canvas`](./doc-block-canvas.mdx) are already unstyled, so there’s no need to wrap those in the `Unstyled` block to ensure that Storybook’s styles don’t bleed into the stories. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block. + - Due to how CSS inheritance works it’s best to always add the Unstyled block to the root of your MDX, and not nested into other elements. The following example will cause some Storybook styles like `color` to be inherited into `CustomComponent` because they are applied to the root `div`: - {/* prettier-ignore-start */} +Due to how CSS inheritance works it’s best to always add the Unstyled block to the root of your MDX, and not nested into other elements. The following example will cause some Storybook styles like `color` to be inherited into `CustomComponent` because they are applied to the root `div`: - ```md -
- - - -
- ``` +```md +
+ + + +
+``` - {/* prettier-ignore-end */} ## Unstyled @@ -71,4 +66,4 @@ import { Unstyled } from '@storybook/addon-docs/blocks'; Type: `React.ReactNode` -Provides the content to which you do *not* want to apply default docs styles. +Provides the content to which you do _not_ want to apply default docs styles. diff --git a/docs/api/doc-blocks/doc-block-useof.mdx b/docs/api/doc-blocks/doc-block-useof.mdx index a47517330bad..455d74e8f6db 100644 --- a/docs/api/doc-blocks/doc-block-useof.mdx +++ b/docs/api/doc-blocks/doc-block-useof.mdx @@ -1,8 +1,7 @@ --- -title: 'useOf' +title: useOf sidebar: order: 18 - title: useOf --- The default blocks supplied by Storybook do not fit all use cases, so you might want to write your own blocks. @@ -35,8 +34,7 @@ export const StoryName = ({ of }) => { ``` {/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta } from '@storybook/addon-docs/blocks'; import { StoryName } from '../.storybook/blocks/StoryName'; import * as ButtonStories from './Button.stories'; @@ -52,24 +50,19 @@ import * as ButtonStories from './Button.stories'; {/* Renders "Button" */} ``` - {/* prettier-ignore-end */} ## useOf ### Type -{/* prettier-ignore-start */} - ```ts ( moduleExportOrType: ModuleExport | 'story' | 'meta' | 'component', - validTypes?: Array<'story' | 'meta' | 'component'> -) => EnhancedResolvedModuleExportType + validTypes?: Array<'story' | 'meta' | 'component'>, +) => EnhancedResolvedModuleExportType; ``` -{/* prettier-ignore-end */} - ### Parameters #### `moduleExportOrType` @@ -82,9 +75,9 @@ Provides the story export, meta export, component export, or CSF file exports fr When the custom block is in an [attached doc](./doc-block-meta.mdx#attached-vs-unattached), it’s also possible to get the primary (first) story, meta, or component by passing in a string instead. This is useful as a fallback, so the `of` prop can be omitted in your block. The most common pattern is using this as `useOf(props.of || 'story')` which will fall back to the primary story if no `of` prop is defined. -* `useOf('story')` returns the annotated primary story in attached mode; error in unattached mode -* `useOf('meta')` returns the annotated meta in attached mode; error in unattached mode -* `useOf('component')` returns the annotated component specified in the meta in attached mode; error in unattached mode +- `useOf('story')` returns the annotated primary story in attached mode; error in unattached mode +- `useOf('meta')` returns the annotated meta in attached mode; error in unattached mode +- `useOf('component')` returns the annotated component specified in the meta in attached mode; error in unattached mode #### `validTypes` diff --git a/docs/api/doc-blocks/index.mdx b/docs/api/doc-blocks/index.mdx index d71c4eb2a286..d0279fecff66 100644 --- a/docs/api/doc-blocks/index.mdx +++ b/docs/api/doc-blocks/index.mdx @@ -2,5 +2,4 @@ title: Doc Blocks sidebar: order: 5 - title: Doc Blocks ---- \ No newline at end of file +--- diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 36be8e4c9114..59b274404ecc 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -1,17 +1,15 @@ --- -title: 'API references' +title: API references hideRendererSelector: true sidebar: order: 12 title: API ---- - -{/* +note: | We intentionally do not use markdown tables here because the required formatting (one row per line) makes it very difficult to read, particularly when comparing changes. Also, using HTML directly allows us to apply a consistent width to the first column. However, this means the links won't work when viewing in GitHub. :( -*/} +--- An overview of all available API references for Storybook. @@ -61,6 +59,7 @@ An overview of all available API references for Storybook. version of your Storybook. + @@ -102,6 +101,7 @@ An overview of all available API references for Storybook. Parameters are static metadata used to configure your stories addons in Storybook. They are specified at the story, meta (component), project (global) levels. + @@ -124,5 +124,6 @@ An overview of all available API references for Storybook. your project. + diff --git a/docs/api/main-config/index.mdx b/docs/api/main-config/index.mdx index 18d625a5de5f..750ca73e9eab 100644 --- a/docs/api/main-config/index.mdx +++ b/docs/api/main-config/index.mdx @@ -2,5 +2,4 @@ title: 'main.js|ts configuration' sidebar: order: 1 - title: main.js|ts configuration ---- \ No newline at end of file +--- diff --git a/docs/api/main-config/main-config-addons.mdx b/docs/api/main-config/main-config-addons.mdx index cb2df239cdf0..b1eb51ff4dc5 100644 --- a/docs/api/main-config/main-config-addons.mdx +++ b/docs/api/main-config/main-config-addons.mdx @@ -1,8 +1,7 @@ --- -title: 'addons' +title: addons sidebar: order: 4 - title: addons --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,8 +12,4 @@ Registers the [addons](../../addons/install-addons.mdx) loaded by Storybook. For each addon's available options, see their respective [documentation](https://storybook.js.org/integrations). -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-babel-default.mdx b/docs/api/main-config/main-config-babel-default.mdx index 25a763fe8006..ba7f14ddacf1 100644 --- a/docs/api/main-config/main-config-babel-default.mdx +++ b/docs/api/main-config/main-config-babel-default.mdx @@ -1,8 +1,7 @@ --- -title: 'babelDefault' +title: babelDefault sidebar: order: 6 - title: babelDefault --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,16 +12,12 @@ Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise - To adjust your Storybook's Babel setup directlyβ€”not via an addonβ€”use [`babel`](./main-config-babel.mdx) instead. - - +To adjust your Storybook's Babel setup directlyβ€”not via an addonβ€”use [`babel`](./main-config-babel.mdx) instead. -{/* prettier-ignore-start */} + -{/* prettier-ignore-end */} - ## `Babel.Config` The options provided by [Babel](https://babeljs.io/docs/options) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon. diff --git a/docs/api/main-config/main-config-babel.mdx b/docs/api/main-config/main-config-babel.mdx index 88203adceb03..0ee8759f4df2 100644 --- a/docs/api/main-config/main-config-babel.mdx +++ b/docs/api/main-config/main-config-babel.mdx @@ -1,8 +1,7 @@ --- -title: 'babel' +title: babel sidebar: order: 5 - title: babel --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,24 +12,20 @@ Customize Storybook's [Babel](https://babeljs.io/) setup. - [Addon authors](../../addons/writing-presets.mdx#babel) should use [`babelDefault`](./main-config-babel-default.mdx) instead, which is applied to the preview config before any user presets have been applied. +[Addon authors](../../addons/writing-presets.mdx#babel) should use [`babelDefault`](./main-config-babel-default.mdx) instead, which is applied to the preview config before any user presets have been applied. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `Babel.Config` The options provided by [Babel](https://babeljs.io/docs/options) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon. - If you have an existing Babel configuration file (e.g., `.babelrc`), it will be automatically detected and used by Storybook without any additional configuration required. - +If you have an existing Babel configuration file (e.g., `.babelrc`), it will be automatically detected and used by Storybook without any additional configuration required. + ## `Options` diff --git a/docs/api/main-config/main-config-build.mdx b/docs/api/main-config/main-config-build.mdx index ebad98b2b0f9..4fe1c2fd50b2 100644 --- a/docs/api/main-config/main-config-build.mdx +++ b/docs/api/main-config/main-config-build.mdx @@ -1,8 +1,7 @@ --- -title: 'build' +title: build sidebar: order: 7 - title: build --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -32,7 +31,7 @@ Configures Storybook's production builds for performance testing purposes by dis - The options documented on this page are automatically enabled when the `--test` flag is provided to the [`storybook build`](../cli-options.mdx#build) command. We encourage you to override these options only if you need to disable a specific feature for your project or if you are debugging a build issue. +The options documented on this page are automatically enabled when the `--test` flag is provided to the [`storybook build`](../cli-options.mdx#build) command. We encourage you to override these options only if you need to disable a specific feature for your project or if you are debugging a build issue. @@ -42,80 +41,52 @@ Type: `boolean` Excludes the `@storybook/addon-docs/blocks` module from the build, which generates automatic documentation with [Docs Blocks](../../writing-docs/doc-blocks.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disabledAddons` Type: `string[]` Sets the list of addons that will be disabled in the build output. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableMDXEntries` Type: `boolean` Enabling this option removes user-written documentation entries in MDX format from the build. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableAutoDocs` Type: `boolean` Prevents automatic documentation generated with the [autodocs](../../writing-docs/autodocs.mdx) feature from being included in the build. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableDocgen` Type: `boolean` Disables [automatic argType](../arg-types.mdx#automatic-argtype-inference) and component property inference with any of the supported static analysis tools based on the framework you are using. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableSourcemaps` Type: `boolean` Overrides the default behavior of generating source maps for the build. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableTreeShaking` Type: `boolean` Disables [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) in the build. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-core.mdx b/docs/api/main-config/main-config-core.mdx index e2531467af84..005796834ab2 100644 --- a/docs/api/main-config/main-config-core.mdx +++ b/docs/api/main-config/main-config-core.mdx @@ -1,8 +1,7 @@ --- -title: 'core' +title: core sidebar: order: 8 - title: core --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -34,12 +33,8 @@ Default: `[]` Configures the allowed hosts for the Storybook dev server, used for Origin and Host header validation. Storybook's localhost and local network (or [`--host`](../cli-options.mdx#dev)) addresses are always allowed. Use this when accessing your local Storybook instance through a reverse proxy (e.g. your webapp dev server). Set to `true` to disable hostname validation (insecure). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `builder` Type: @@ -55,16 +50,14 @@ Type: Configures Storybook's builder, [Vite](../../builders/vite.mdx) or [Webpack](../../builders/webpack.mdx). - With the new [Framework API](../new-frameworks.mdx), [`framework.options.builder`](./main-config-framework.mdx#optionsbuilder) is now the preferred way to configure the builder. - You should only use `core.builder.options` if you need to configure a builder that is not part of a framework. - +With the new [Framework API](../new-frameworks.mdx), [`framework.options.builder`](./main-config-framework.mdx#optionsbuilder) is now the preferred way to configure the builder. -{/* prettier-ignore-start */} +You should only use `core.builder.options` if you need to configure a builder that is not part of a framework. - + -{/* prettier-ignore-end */} + ## `channelOptions` @@ -85,7 +78,6 @@ Configures the channel used by Storybook to communicate between the manager and Only two properties are likely to be used: - ### `channelOptions.maxDepth` Type: `number` @@ -102,75 +94,51 @@ Enable CORS headings to run document in a "secure context". See [SharedArrayBuff This enables these headers in development-mode: -* `Cross-Origin-Opener-Policy: same-origin` -* `Cross-Origin-Embedder-Policy: require-corp` - -{/* prettier-ignore-start */} +- `Cross-Origin-Opener-Policy: same-origin` +- `Cross-Origin-Embedder-Policy: require-corp` -{/* prettier-ignore-end */} - ## `disableProjectJson` Type: `boolean` Disables the generation of `project.json`, a file containing Storybook metadata -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `disableTelemetry` Type: `boolean` Disables Storybook's [telemetry collection](../../configure/telemetry.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `disableWebpackDefaults` Type: `boolean` Disables Storybook's default Webpack configuration. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `disableWhatsNewNotifications` Type: `boolean` Disables the "What's New" notifications in the UI for new Storybook versions and ecosystem updates (e.g., [addons](https://storybook.js.org/integrations/), [content](https://storybook.js.org/blog/), etc.). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `enableCrashReports` Type: `boolean` Enable crash reports to be sent to Storybook [telemetry](../../configure/telemetry.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `renderer` Type: `RendererName` diff --git a/docs/api/main-config/main-config-docs.mdx b/docs/api/main-config/main-config-docs.mdx index 7c28850020ae..a31599bb5ef3 100644 --- a/docs/api/main-config/main-config-docs.mdx +++ b/docs/api/main-config/main-config-docs.mdx @@ -1,8 +1,7 @@ --- -title: 'docs' +title: docs sidebar: order: 9 - title: docs --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -26,20 +25,12 @@ Default: `'Docs'` Name used for generated documentation pages. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `docsMode` Type: `boolean` Only show documentation pages in the sidebar (usually set with the `--docs` CLI flag). -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-env.mdx b/docs/api/main-config/main-config-env.mdx index 5ed5392bf429..487fe6c911f2 100644 --- a/docs/api/main-config/main-config-env.mdx +++ b/docs/api/main-config/main-config-env.mdx @@ -1,8 +1,7 @@ --- -title: 'env' +title: env sidebar: order: 10 - title: env --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,8 +10,4 @@ Type: `(config: { [key: string]: string }) => { [key: string]: string }` Defines custom Storybook [environment variables](../../configure/environment-variables.mdx#using-storybook-configuration). -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-features.mdx b/docs/api/main-config/main-config-features.mdx index f119c8d2239b..62fbce69a424 100644 --- a/docs/api/main-config/main-config-features.mdx +++ b/docs/api/main-config/main-config-features.mdx @@ -1,8 +1,7 @@ --- -title: 'features' +title: features sidebar: order: 11 - title: features --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -32,6 +31,7 @@ Type: viewport?: boolean; } ``` + @@ -55,6 +55,7 @@ Type: viewport?: boolean; } ``` + @@ -77,8 +78,8 @@ Type: viewport?: boolean; } ``` - + Enables Storybook's additional features. @@ -110,12 +111,8 @@ Default: `true` Filter args with a "target" on the type from the render function. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `backgrounds` Type: `boolean` @@ -160,12 +157,8 @@ Type: `boolean` Set `NODE_ENV` to `'development'` in built Storybooks for better testing and debugging capabilities. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `experimentalCodeExamples` @@ -188,12 +181,8 @@ Type: `boolean` Enable the [experimental `.test` method with the CSF Next format](../csf/csf-next#storytest). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `highlight` @@ -218,12 +207,8 @@ Type: `boolean` Apply decorators from preview.js before decorators from addons or frameworks. [More information](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#changed-decorator-order-between-previewjs-and-addonsframeworks). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `measure` Type: `boolean` diff --git a/docs/api/main-config/main-config-framework.mdx b/docs/api/main-config/main-config-framework.mdx index 3b2a2e7b38e4..6da060baaa5b 100644 --- a/docs/api/main-config/main-config-framework.mdx +++ b/docs/api/main-config/main-config-framework.mdx @@ -1,8 +1,7 @@ --- -title: 'framework' +title: framework sidebar: order: 2 - title: framework --- (**Required**) @@ -13,12 +12,8 @@ Type: `FrameworkName | { name: FrameworkName; options?: FrameworkOptions }` Configures Storybook based on a set of [framework-specific](../../configure/integration/frameworks.mdx) settings. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `name` Type: `string` diff --git a/docs/api/main-config/main-config-indexers.mdx b/docs/api/main-config/main-config-indexers.mdx index 9fce870fcc6c..05221840f5db 100644 --- a/docs/api/main-config/main-config-indexers.mdx +++ b/docs/api/main-config/main-config-indexers.mdx @@ -1,14 +1,15 @@ --- -title: 'indexers' +title: indexers sidebar: order: 12 - title: indexers --- (⚠️ **Experimental**) - While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.mdx). + +While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.mdx). + Parent: [main.js|ts configuration](./main-config.mdx) @@ -21,12 +22,8 @@ The indexers API is an advanced feature that allows you to customize Storybook's They are defined as a function that returns the full list of indexers, including the existing ones. This allows you to add your own indexer to the list, or to replace an existing one: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Unless your indexer is doing something relatively trivial (e.g. [indexing stories with a different naming convention](../../configure/user-interface/sidebar-and-urls.mdx#story-indexers)), in addition to indexing the file, you will likely need to [transpile it to CSF](#transpiling-to-csf) so that Storybook can read them in the browser. ## `Indexer` @@ -157,7 +154,7 @@ Default: Auto-generated from [`title`](#title) Define the custom id for meta of the entry. -If specified, the export default (meta) in the CSF file *must* have a corresponding `id` property, to be correctly matched. +If specified, the export default (meta) in the CSF file _must_ have a corresponding `id` property, to be correctly matched. ##### `name` @@ -183,12 +180,8 @@ Determines the location of the entry in the sidebar. Most of the time, you should **not** specify a title, so that your indexer will use the default naming behavior. When specifying a title, you **must** use the [`makeTitle`](#maketitle) function provided in [`IndexerOptions`](#indexeroptions) to also use this behavior. For example, here's an indexer that merely appends a "Custom" prefix to the title derived from the file name: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ##### `__id` Type: `string` @@ -203,7 +196,7 @@ Only use this if you need to override the auto-generated id. ## Transpiling to CSF -The value of [`importPath`](#importpath) in an [`IndexInput`](#indexinput) must resolve to a [CSF](../csf/index.mdx) file. Most custom indexers, however, are only necessary because the input is *not* CSF. Therefore, you will likely need to transpile the input to CSF, so that Storybook can read it in the browser and render your stories. +The value of [`importPath`](#importpath) in an [`IndexInput`](#indexinput) must resolve to a [CSF](../csf/index.mdx) file. Most custom indexers, however, are only necessary because the input is _not_ CSF. Therefore, you will likely need to transpile the input to CSF, so that Storybook can read it in the browser and render your stories. Transpiling the custom source format to CSF is beyond the scope of this documentation. This transpilation is often done at the builder level ([Vite](../../builders/vite.mdx) and/or [Webpack](../../builders/webpack.mdx)), and we recommend using [unplugin](https://github.com/unjs/unplugin) to create plugins for multiple builders. @@ -275,229 +268,223 @@ export const Primary = { Some example usages of custom indexers include:
- Generating stories dynamically from fixture data or API endpoints - - This indexer generates stories for components based on JSON fixture data. It looks for `*.stories.json` files in the project, adds them to the index and separately converts their content to CSF. - - {/* prettier-ignore-start */} + +Generating stories dynamically from fixture data or API endpoints + - +This indexer generates stories for components based on JSON fixture data. It looks for `*.stories.json` files in the project, adds them to the index and separately converts their content to CSF. - {/* prettier-ignore-end */} + - An example input JSON file could look like this: +An example input JSON file could look like this: - ```json - { - "Button": { - "componentPath": "./button/Button.jsx", - "stories": { - "Primary": { - "args": { - "primary": true - }, - "Secondary": { - "args": { - "primary": false - } - } - } - }, - "Dialog": { - "componentPath": "./dialog/Dialog.jsx", - "stories": { - "Closed": {}, - "Open": { - "args": { - "isOpen": true - } +```json +{ + "Button": { + "componentPath": "./button/Button.jsx", + "stories": { + "Primary": { + "args": { + "primary": true }, + "Secondary": { + "args": { + "primary": false + } } } + }, + "Dialog": { + "componentPath": "./dialog/Dialog.jsx", + "stories": { + "Closed": {}, + "Open": { + "args": { + "isOpen": true + } + }, + } } - ``` +} +``` - A builder plugin will then need to transform the JSON file into a regular CSF file. This transformation could be done with a Vite plugin similar to this: +A builder plugin will then need to transform the JSON file into a regular CSF file. This transformation could be done with a Vite plugin similar to this: - ```ts - // vite-plugin-storybook-json-stories.ts +```ts +// vite-plugin-storybook-json-stories.ts - import type { PluginOption } from 'vite'; - import fs from 'fs/promises'; +import type { PluginOption } from 'vite'; +import fs from 'fs/promises'; - function JsonStoriesPlugin(): PluginOption { - return { - name: 'vite-plugin-storybook-json-stories', - load(id) { - if (!id.startsWith('virtual:jsonstories')) { - return; - } +function JsonStoriesPlugin(): PluginOption { + return { + name: 'vite-plugin-storybook-json-stories', + load(id) { + if (!id.startsWith('virtual:jsonstories')) { + return; + } - const [, fileName, componentName] = id.split('--'); - const content = JSON.parse(fs.readFileSync(fileName)); + const [, fileName, componentName] = id.split('--'); + const content = JSON.parse(fs.readFileSync(fileName)); - const { componentPath, stories } = getComponentStoriesFromJson(content, componentName); + const { componentPath, stories } = getComponentStoriesFromJson(content, componentName); - return ` - import ${componentName} from '${componentPath}'; + return ` + import ${componentName} from '${componentPath}'; - export default { component: ${componentName} }; + export default { component: ${componentName} }; + + ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)} + `; + }, + }; +} +``` - ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)} - `; - }, - }; - } - ```
- Generating stories with an alternative API +Generating stories with an alternative API + +You can use a custom indexer and builder plugin to create your API to define stories extending the CSF format. To learn more, see the following [proof of concept](https://stackblitz.com/edit/github-h2rgfk?file=README.md) to set up a custom indexer to generate stories dynamically. It contains everything needed to support such a feature, including the indexer, a Vite plugin, and a Webpack loader. - You can use a custom indexer and builder plugin to create your API to define stories extending the CSF format. To learn more, see the following [proof of concept](https://stackblitz.com/edit/github-h2rgfk?file=README.md) to set up a custom indexer to generate stories dynamically. It contains everything needed to support such a feature, including the indexer, a Vite plugin, and a Webpack loader.
- Defining stories in non-JavaScript language +Defining stories in non-JavaScript language - Custom indexers can be used for an advanced purpose: defining stories in any language, including template languages, and converting the files to CSF. To see examples of this in action, you can refer to [`@storybook/addon-svelte-csf`](https://github.com/storybookjs/addon-svelte-csf) for Svelte template syntax and [`storybook-vue-addon`](https://github.com/tobiasdiez/storybook-vue-addon) for Vue template syntax. -
+Custom indexers can be used for an advanced purpose: defining stories in any language, including template languages, and converting the files to CSF. To see examples of this in action, you can refer to [`@storybook/addon-svelte-csf`](https://github.com/storybookjs/addon-svelte-csf) for Svelte template syntax and [`storybook-vue-addon`](https://github.com/tobiasdiez/storybook-vue-addon) for Vue template syntax. +
- Adding sidebar links from a URL collection - - The indexer API is flexible enough to let you process arbitrary content, so long as your framework tooling can transform the exports in that content into actual stories it can run. This advanced example demonstrates how you can create a custom indexer to process a collection of URLs, extract the title and URL from each page, and render them as sidebar links in the UI. Implemented with Svelte, it can be adapted to any framework. - - Start by creating the URL collection file (i.e., `src/MyLinks.url.js`) with a list of URLs listed as named exports. The indexer will use the export name as the story title and the value as the unique identifier. - - ```js title="MyLinks.url.js" - export default {}; - - export const DesignTokens = 'https://www.designtokens.org/'; - export const CobaltUI = 'https://cobalt-ui.pages.dev/'; - export const MiseEnMode = 'https://mode.place/'; - export const IndexerAPI = 'https://github.com/storybookjs/storybook/discussions/23176'; - ``` - - Adjust your Vite configuration file to include a custom plugin complementing the indexer. This will allow Storybook to process and import the URL collection file as stories. - - ```ts title="vite.config.ts" - import * as acorn from 'acorn'; - import * as walk from 'acorn-walk'; - import { defineConfig, type Plugin } from 'vite'; - import { svelte } from '@sveltejs/vite-plugin-svelte'; - - function StorybookUrlLinksPlugin(): Plugin { - return { - name: 'storybook-url-links', - async transform(code: string, id: string) { - if (id.endsWith('.url.js')) { - const ast = acorn.parse(code, { - ecmaVersion: 2020, - sourceType: 'module', - }); - - const namedExports: string[] = []; - let defaultExport = 'export default {};'; - - walk.simple(ast, { - // Extracts the named exports, those represent our stories, and for each of them, we'll return a valid Svelte component. - ExportNamedDeclaration(node: acorn.ExportNamedDeclaration) { - if ( - node.declaration && - node.declaration.type === 'VariableDeclaration' - ) { - node.declaration.declarations.forEach((declaration) => { - if ('name' in declaration.id) { - namedExports.push(declaration.id.name); - } - }); - } - }, - // Preserve our default export. - ExportDefaultDeclaration(node: acorn.ExportDefaultDeclaration) { - defaultExport = code.slice(node.start, node.end); - }, - }); - - return { - code: ` - import RedirectBack from '../../.storybook/components/RedirectBack.svelte'; - ${namedExports - .map( - (name) => - `export const ${name} = () => new RedirectBack();` - ) - .join('\n')} - ${defaultExport} - `, - map: null, - }; - } - }, - }; - } +Adding sidebar links from a URL collection + +The indexer API is flexible enough to let you process arbitrary content, so long as your framework tooling can transform the exports in that content into actual stories it can run. This advanced example demonstrates how you can create a custom indexer to process a collection of URLs, extract the title and URL from each page, and render them as sidebar links in the UI. Implemented with Svelte, it can be adapted to any framework. + +Start by creating the URL collection file (i.e., `src/MyLinks.url.js`) with a list of URLs listed as named exports. The indexer will use the export name as the story title and the value as the unique identifier. + +```js title="MyLinks.url.js" +export default {}; - export default defineConfig({ - plugins: [StorybookUrlLinksPlugin(), svelte()], - }) - ``` - - Update your Storybook configuration (i.e., `.storybook/main.js|ts`) to include the custom indexer. - - ```ts title=".storybook/main.js|ts" - // Replace your-framework with the framework you are using, e.g. sveltekit or svelte-vite - import type { StorybookConfig } from '@storybook/your-framework'; - import type { Indexer } from 'storybook/internal/types'; - - const urlIndexer: Indexer = { - test: /\.url\.js$/, - createIndex: async (fileName, { makeTitle }) => { - const fileData = await import(fileName); - - return Object.entries(fileData) - .filter(([key]) => key != 'default') - .map(([name, url]) => { - return { - type: 'docs', - importPath: fileName, - exportName: name, - title: makeTitle(name) - .replace(/([a-z])([A-Z])/g, '$1 $2') - .trim(), - __id: `url--${name}--${encodeURIComponent(url as string)}`, - tags: ['!autodocs', 'url'] - }; +export const DesignTokens = 'https://www.designtokens.org/'; +export const CobaltUI = 'https://cobalt-ui.pages.dev/'; +export const MiseEnMode = 'https://mode.place/'; +export const IndexerAPI = 'https://github.com/storybookjs/storybook/discussions/23176'; +``` + +Adjust your Vite configuration file to include a custom plugin complementing the indexer. This will allow Storybook to process and import the URL collection file as stories. + +```ts title="vite.config.ts" +import * as acorn from 'acorn'; +import * as walk from 'acorn-walk'; +import { defineConfig, type Plugin } from 'vite'; +import { svelte } from '@sveltejs/vite-plugin-svelte'; + +function StorybookUrlLinksPlugin(): Plugin { + return { + name: 'storybook-url-links', + async transform(code: string, id: string) { + if (id.endsWith('.url.js')) { + const ast = acorn.parse(code, { + ecmaVersion: 2020, + sourceType: 'module', + }); + + const namedExports: string[] = []; + let defaultExport = 'export default {};'; + + walk.simple(ast, { + // Extracts the named exports, those represent our stories, and for each of them, we'll return a valid Svelte component. + ExportNamedDeclaration(node: acorn.ExportNamedDeclaration) { + if (node.declaration && node.declaration.type === 'VariableDeclaration') { + node.declaration.declarations.forEach((declaration) => { + if ('name' in declaration.id) { + namedExports.push(declaration.id.name); + } + }); + } + }, + // Preserve our default export. + ExportDefaultDeclaration(node: acorn.ExportDefaultDeclaration) { + defaultExport = code.slice(node.start, node.end); + }, }); - } - }; - const config: StorybookConfig = { - stories: ['../src/**/*.stories.@(js|ts|svelte)', '../src/**/*.url.js'], - framework: { - name: '@storybook/svelte-vite', - options: {}, + return { + code: ` + import RedirectBack from '../../.storybook/components/RedirectBack.svelte'; + ${namedExports + .map((name) => `export const ${name} = () => new RedirectBack();`) + .join('\n')} + ${defaultExport} + `, + map: null, + }; + } }, - experimental_indexers: async (existingIndexers) => [urlIndexer, ...existingIndexers] }; - export default config; - ``` +} - Add a Storybook UI configuration file (i.e., `.storybook/manager.js|ts`) to render the indexed URLs as sidebar links in the UI: +export default defineConfig({ + plugins: [StorybookUrlLinksPlugin(), svelte()], +}); +``` - ```ts title=".storybook/manager.ts" - import { addons } from 'storybook/manager-api'; +Update your Storybook configuration (i.e., `.storybook/main.js|ts`) to include the custom indexer. + +```ts title=".storybook/main.js|ts" +// Replace your-framework with the framework you are using, e.g. sveltekit or svelte-vite +import type { StorybookConfig } from '@storybook/your-framework'; +import type { Indexer } from 'storybook/internal/types'; + +const urlIndexer: Indexer = { + test: /\.url\.js$/, + createIndex: async (fileName, { makeTitle }) => { + const fileData = await import(fileName); + + return Object.entries(fileData) + .filter(([key]) => key != 'default') + .map(([name, url]) => { + return { + type: 'docs', + importPath: fileName, + exportName: name, + title: makeTitle(name) + .replace(/([a-z])([A-Z])/g, '$1 $2') + .trim(), + __id: `url--${name}--${encodeURIComponent(url as string)}`, + tags: ['!autodocs', 'url'], + }; + }); + }, +}; - import SidebarLabelWrapper from './components/SidebarLabelWrapper.tsx'; +const config: StorybookConfig = { + stories: ['../src/**/*.stories.@(js|ts|svelte)', '../src/**/*.url.js'], + framework: { + name: '@storybook/svelte-vite', + options: {}, + }, + experimental_indexers: async (existingIndexers) => [urlIndexer, ...existingIndexers], +}; +export default config; +``` - addons.setConfig({ - sidebar: { - renderLabel: (item) => SidebarLabelWrapper({ item }), - }, - }); - ``` +Add a Storybook UI configuration file (i.e., `.storybook/manager.js|ts`) to render the indexed URLs as sidebar links in the UI: + +```ts title=".storybook/manager.ts" +import { addons } from 'storybook/manager-api'; + +import SidebarLabelWrapper from './components/SidebarLabelWrapper.tsx'; + +addons.setConfig({ + sidebar: { + renderLabel: (item) => SidebarLabelWrapper({ item }), + }, +}); +``` - This example's code and live demo are available on [StackBlitz](https://stackblitz.com/~/github.com/Sidnioulz/storybook-sidebar-urls). +This example's code and live demo are available on [StackBlitz](https://stackblitz.com/~/github.com/Sidnioulz/storybook-sidebar-urls).
diff --git a/docs/api/main-config/main-config-log-level.mdx b/docs/api/main-config/main-config-log-level.mdx index 064be3953f3f..aa8bc52c69a5 100644 --- a/docs/api/main-config/main-config-log-level.mdx +++ b/docs/api/main-config/main-config-log-level.mdx @@ -1,8 +1,7 @@ --- -title: 'logLevel' +title: logLevel sidebar: order: 13 - title: logLevel --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,8 +12,4 @@ Default: `'info'` Configures Storybook's logs in the browser terminal. Useful for debugging. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-manager-head.mdx b/docs/api/main-config/main-config-manager-head.mdx index 8af2641db0c1..29a1a47302e5 100644 --- a/docs/api/main-config/main-config-manager-head.mdx +++ b/docs/api/main-config/main-config-manager-head.mdx @@ -1,8 +1,7 @@ --- -title: 'managerHead' +title: managerHead sidebar: order: 14 - title: managerHead --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,14 +12,10 @@ Programmatically adjust the manager's `` of your Storybook. For example, l - If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead. - +If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead. + For example, you can conditionally add scripts or styles, depending on the environment: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-preview-annotations.mdx b/docs/api/main-config/main-config-preview-annotations.mdx index cf5a1bea2419..d2d66b889d9e 100644 --- a/docs/api/main-config/main-config-preview-annotations.mdx +++ b/docs/api/main-config/main-config-preview-annotations.mdx @@ -1,8 +1,7 @@ --- -title: 'previewAnnotations' +title: previewAnnotations sidebar: order: 15 - title: previewAnnotations --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -12,7 +11,9 @@ Type: `string[] | ((config: string[], options: Options) => string[] | Promise - Mostly used by [frameworks](../../contribute/framework.mdx#previewjs-example). Storybook users and [addon authors](../../addons/writing-presets.mdx) should add scripts to [`preview.js`](../../configure/index.mdx#configure-story-rendering) instead. + +Mostly used by [frameworks](../../contribute/framework.mdx#previewjs-example). Storybook users and [addon authors](../../addons/writing-presets.mdx) should add scripts to [`preview.js`](../../configure/index.mdx#configure-story-rendering) instead. + ```ts diff --git a/docs/api/main-config/main-config-preview-body.mdx b/docs/api/main-config/main-config-preview-body.mdx index 0777c1a35904..e904ffe2523f 100644 --- a/docs/api/main-config/main-config-preview-body.mdx +++ b/docs/api/main-config/main-config-preview-body.mdx @@ -1,8 +1,7 @@ --- -title: 'previewBody' +title: previewBody sidebar: order: 16 - title: previewBody --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,14 +12,10 @@ Programmatically adjust the [preview ``](../../configure/story-rendering.m - If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../../configure/story-rendering.mdx#adding-to-body) instead. - +If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../../configure/story-rendering.mdx#adding-to-body) instead. + For example, you can conditionally add scripts or styles, depending on the environment: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-preview-head.mdx b/docs/api/main-config/main-config-preview-head.mdx index 8745bc524edb..5bf40ecb9321 100644 --- a/docs/api/main-config/main-config-preview-head.mdx +++ b/docs/api/main-config/main-config-preview-head.mdx @@ -1,8 +1,7 @@ --- -title: 'previewHead' +title: previewHead sidebar: order: 17 - title: previewHead --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -12,13 +11,11 @@ Type: `(head: string) => string` Programmatically adjust the [preview ``](../../configure/story-rendering.mdx#adding-to-head) of your Storybook. Most often used by [addon authors](../../addons/writing-presets.mdx#ui-configuration). - If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](../../configure/story-rendering.mdx#adding-to-head) instead. + +If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](../../configure/story-rendering.mdx#adding-to-head) instead. + For example, you can conditionally add scripts or styles, depending on the environment: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-refs.mdx b/docs/api/main-config/main-config-refs.mdx index 33f7c69c5803..581f23503f80 100644 --- a/docs/api/main-config/main-config-refs.mdx +++ b/docs/api/main-config/main-config-refs.mdx @@ -1,8 +1,7 @@ --- -title: 'refs' +title: refs sidebar: order: 18 - title: refs --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -19,28 +18,16 @@ Type: Configures [Storybook composition](../../sharing/storybook-composition.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Using a function You can use a function to dynamically configure refs: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Disable a ref Some package dependencies automatically [compose their Storybook in yours](../../sharing/package-composition.mdx). You can disable this behavior by setting `disable` to `true` for the package name: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-static-dirs.mdx b/docs/api/main-config/main-config-static-dirs.mdx index 0207e0b5e67d..f33305cd3d09 100644 --- a/docs/api/main-config/main-config-static-dirs.mdx +++ b/docs/api/main-config/main-config-static-dirs.mdx @@ -1,8 +1,7 @@ --- -title: 'staticDirs' +title: staticDirs sidebar: order: 19 - title: staticDirs --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,22 +10,16 @@ Type: `(string | { from: string; to: string })[]` Sets a list of directories of [static files](../../configure/integration/images-and-assets.mdx#serving-static-files-via-storybook-configuration) to be loaded by Storybook. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - + When using Vite-based frameworks, additional directories may be copied to your build directory because of Vite's own [static asset handling](https://vite.dev/guide/assets#the-public-directory). You can set Vite's `publicDir` option to `false` to disable this behavior. + ## With configuration objects You can also use a configuration object to define the directories: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} \ No newline at end of file diff --git a/docs/api/main-config/main-config-stories.mdx b/docs/api/main-config/main-config-stories.mdx index 9555cc1e356e..ef50a26d0f06 100644 --- a/docs/api/main-config/main-config-stories.mdx +++ b/docs/api/main-config/main-config-stories.mdx @@ -1,8 +1,7 @@ --- -title: 'stories' +title: stories sidebar: order: 3 - title: stories --- (**Required**) @@ -25,16 +24,14 @@ Configures Storybook to load stories from the specified locations. The intention └── Button.stories.ts ``` -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). - Keep in mind that some addons may assume Storybook's default naming convention. +If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). + +Keep in mind that some addons may assume Storybook's default naming convention. + ## With an array of globs @@ -43,24 +40,16 @@ Storybook will load stories from your project as found by this array of globs (p Stories are loaded in the order they are defined in the array. This allows you to control the order in which stories are displayed in the sidebar: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## With a configuration object Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. This object is of the type `StoriesSpecifier`, defined below. For example, if you wanted to load your stories from a `packages/components` directory, you could adjust your `stories` configuration field into the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - When Storybook starts, it will look for any file containing the `stories` extension inside the `packages/components` directory and generate the titles for your stories. ### `StoriesSpecifier` @@ -102,13 +91,11 @@ When [auto-titling](../../configure/user-interface/sidebar-and-urls.mdx#csf-30-a ## With a custom implementation - πŸ’‘ Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability. + +Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability. + You can also adjust your Storybook configuration and implement custom logic to load your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve. In that case, you could adjust your configuration as follows: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-swc.mdx b/docs/api/main-config/main-config-swc.mdx index a896e63079f3..16d245866077 100644 --- a/docs/api/main-config/main-config-swc.mdx +++ b/docs/api/main-config/main-config-swc.mdx @@ -1,8 +1,7 @@ --- -title: 'swc' +title: swc sidebar: order: 20 - title: swc --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,12 +10,8 @@ Type: `(config: swc.Options, options: Options) => swc.Options | Promise -{/* prettier-ignore-end */} - ## `SWC.Options` The options provided by [SWC](https://swc.rs/) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-swc`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-swc) addon. diff --git a/docs/api/main-config/main-config-tags.mdx b/docs/api/main-config/main-config-tags.mdx index d0cc7613bb4a..96bd848ddff5 100644 --- a/docs/api/main-config/main-config-tags.mdx +++ b/docs/api/main-config/main-config-tags.mdx @@ -1,8 +1,7 @@ --- -title: 'tags' +title: tags sidebar: order: 21 - title: tags --- Parent: [main.js|ts configuration](./main-config.mdx) diff --git a/docs/api/main-config/main-config-typescript.mdx b/docs/api/main-config/main-config-typescript.mdx index c23f8e693a77..af07b03a457d 100644 --- a/docs/api/main-config/main-config-typescript.mdx +++ b/docs/api/main-config/main-config-typescript.mdx @@ -1,35 +1,38 @@ --- -title: 'typescript' +title: typescript sidebar: order: 22 - title: typescript --- Parent: [main.js|ts configuration](./main-config.mdx) Type: - - ```ts - { - check?: boolean; - checkOptions?: CheckOptions; - reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false; - reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions; - skipCompiler?: boolean; - } - ``` - - - - ```ts - { - check?: boolean; - checkOptions?: CheckOptions; - skipCompiler?: boolean; - } - ``` - + + +```ts +{ + check?: boolean; + checkOptions?: CheckOptions; + reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false; + reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions; + skipCompiler?: boolean; +} +``` + + + + + +```ts +{ + check?: boolean; + checkOptions?: CheckOptions; + skipCompiler?: boolean; +} +``` + + Configures how Storybook handles [TypeScript files](../../configure/integration/typescript.mdx). @@ -39,54 +42,40 @@ Type: `boolean` Optionally run [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin). Note that because this uses a Webpack plugin, it is only available when using the [Webpack builder](../../builders/webpack.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `checkOptions` Type: `CheckOptions` Options to pass to `fork-ts-checker-webpack-plugin`, if [enabled](#check). See [docs for available options](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/blob/v4.1.6/README.md#options). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - - ## `reactDocgen` - - Type: `'react-docgen' | 'react-docgen-typescript' | false` + - Default: +## `reactDocgen` - * `false`: if `@storybook/react` is not installed - * `'react-docgen'`: if `@storybook/react` is installed +Type: `'react-docgen' | 'react-docgen-typescript' | false` - Configures which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete. +Default: - {/* prettier-ignore-start */} +- `false`: if `@storybook/react` is not installed +- `'react-docgen'`: if `@storybook/react` is installed - +Configures which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete. - {/* prettier-ignore-end */} + - ## `reactDocgenTypescriptOptions` +## `reactDocgenTypescriptOptions` - Type: `ReactDocgenTypescriptOptions` +Type: `ReactDocgenTypescriptOptions` - Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See docs for available options [for Webpack projects](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) or [for Vite projects](https://github.com/joshwooding/vite-plugin-react-docgen-typescript). +Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See docs for available options [for Webpack projects](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) or [for Vite projects](https://github.com/joshwooding/vite-plugin-react-docgen-typescript). - {/* prettier-ignore-start */} + - - - {/* prettier-ignore-end */} - + ## `skipCompiler` @@ -94,8 +83,4 @@ Type: `boolean` Disable parsing of TypeScript files through the compiler, which is used for Webpack5. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-vite-final.mdx b/docs/api/main-config/main-config-vite-final.mdx index c0761375db83..1169f59e895d 100644 --- a/docs/api/main-config/main-config-vite-final.mdx +++ b/docs/api/main-config/main-config-vite-final.mdx @@ -1,8 +1,7 @@ --- -title: 'viteFinal' +title: viteFinal sidebar: order: 23 - title: viteFinal --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,12 +10,8 @@ Type: `(config: Vite.InlineConfig, options: Options) => Vite.InlineConfig | Prom Customize Storybook's Vite setup when using the [Vite builder](../../builders/vite.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `Options` Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }` diff --git a/docs/api/main-config/main-config-webpack-final.mdx b/docs/api/main-config/main-config-webpack-final.mdx index 07139fbd8dc9..360f90afd0b1 100644 --- a/docs/api/main-config/main-config-webpack-final.mdx +++ b/docs/api/main-config/main-config-webpack-final.mdx @@ -1,8 +1,7 @@ --- -title: 'webpackFinal' +title: webpackFinal sidebar: order: 24 - title: webpackFinal --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,12 +10,8 @@ Type: `async (config: Config, options: WebpackOptions) => Config` Customize Storybook's Webpack setup when using the [webpack builder](../../builders/webpack.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `Options` Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }` diff --git a/docs/api/main-config/main-config.mdx b/docs/api/main-config/main-config.mdx index bdcd243df931..a6e550a7ebf9 100644 --- a/docs/api/main-config/main-config.mdx +++ b/docs/api/main-config/main-config.mdx @@ -1,5 +1,5 @@ --- -title: 'Main configuration' +title: Main configuration sidebar: order: 1 title: Overview @@ -7,7 +7,6 @@ sidebar: The main configuration defines a Storybook project's behavior, including the location of stories, addons to use, feature flags, and other project-specific settings. - ## The main configuration file: `main.js` or `main.ts` @@ -20,36 +19,32 @@ This configuration is defined in `.storybook/main.js|ts`, which is located relat A typical Storybook configuration file looks like this: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## config An object to configure Storybook containing the following properties: -* [`framework`](./main-config-framework.mdx) (Required) -* [`stories`](./main-config-stories.mdx) (Required) -* [`addons`](./main-config-addons.mdx) -* [`babel`](./main-config-babel.mdx) -* [`babelDefault`](./main-config-babel-default.mdx) -* [`build`](./main-config-build.mdx) -* [`core`](./main-config-core.mdx) -* [`docs`](./main-config-docs.mdx) -* [`env`](./main-config-env.mdx) -* [`features`](./main-config-features.mdx) -* [`indexers`](./main-config-indexers.mdx) (⚠️ Experimental) -* [`logLevel`](./main-config-log-level.mdx) -* [`managerHead`](./main-config-manager-head.mdx) -* [`previewAnnotations`](./main-config-preview-annotations.mdx) -* [`previewBody`](./main-config-preview-body.mdx) -* [`previewHead`](./main-config-preview-head.mdx) -* [`refs`](./main-config-refs.mdx) -* [`staticDirs`](./main-config-static-dirs.mdx) -* [`swc`](./main-config-swc.mdx) -* [`tags`](./main-config-tags.mdx) -* [`typescript`](./main-config-typescript.mdx) -* [`viteFinal`](./main-config-vite-final.mdx) -* [`webpackFinal`](./main-config-webpack-final.mdx) +- [`framework`](./main-config-framework.mdx) (Required) +- [`stories`](./main-config-stories.mdx) (Required) +- [`addons`](./main-config-addons.mdx) +- [`babel`](./main-config-babel.mdx) +- [`babelDefault`](./main-config-babel-default.mdx) +- [`build`](./main-config-build.mdx) +- [`core`](./main-config-core.mdx) +- [`docs`](./main-config-docs.mdx) +- [`env`](./main-config-env.mdx) +- [`features`](./main-config-features.mdx) +- [`indexers`](./main-config-indexers.mdx) (⚠️ Experimental) +- [`logLevel`](./main-config-log-level.mdx) +- [`managerHead`](./main-config-manager-head.mdx) +- [`previewAnnotations`](./main-config-preview-annotations.mdx) +- [`previewBody`](./main-config-preview-body.mdx) +- [`previewHead`](./main-config-preview-head.mdx) +- [`refs`](./main-config-refs.mdx) +- [`staticDirs`](./main-config-static-dirs.mdx) +- [`swc`](./main-config-swc.mdx) +- [`tags`](./main-config-tags.mdx) +- [`typescript`](./main-config-typescript.mdx) +- [`viteFinal`](./main-config-vite-final.mdx) +- [`webpackFinal`](./main-config-webpack-final.mdx) diff --git a/docs/api/new-frameworks.mdx b/docs/api/new-frameworks.mdx index 25809dd92f35..2f6ecf8c039c 100644 --- a/docs/api/new-frameworks.mdx +++ b/docs/api/new-frameworks.mdx @@ -1,8 +1,7 @@ --- -title: 'Frameworks' +title: Frameworks sidebar: order: 7 - title: Frameworks --- Storybook is architected to support diverse web frameworks, including React, Vue, Angular, Web Components, Svelte, and over a dozen others. This guide helps you get started on adding new framework support for Storybook. @@ -46,12 +45,8 @@ These scripts pass an `options` object to `storybook/internal/server`, a library For example, here’s the boilerplate to start the dev server with `storybook dev`: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Thus the essence of adding framework presets is just filling in that options object. ### Server options @@ -60,24 +55,16 @@ As described above, the server `options` object does the heavy lifting of config Let’s look at the `@storybook/vue`’s options definition: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - The value of the `framework` option (i.e., β€˜vue’) is something that gets passed to addons and allows them to do specific tasks related to your framework. The essence of this file is the framework presets, and these are standard [Storybook presets](../addons/writing-presets.mdx) -- you can look at framework packages in the Storybook monorepo (e.g. [React](https://github.com/storybookjs/storybook/blob/next/code/frameworks/react-vite/src/preset.ts), [Vue](https://github.com/storybookjs/storybook/blob/next/code/frameworks/vue3-vite/src/preset.ts), [Web Components](https://github.com/storybookjs/storybook/blob/next/code/frameworks/web-components-vite/src/preset.ts)) to see examples of framework-specific customizations. While developing your custom framework, not maintained by Storybook, you can specify the path to the location file with the `frameworkPath` key: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - You can add a relative path to `frameworkPath`. Don't forget that they resolve from the Storybook configuration directory (i.e., `.storybook`) by default. Make sure the `frameworkPath` ends up at the `dist/client/index.js` file within your framework app. @@ -92,52 +79,32 @@ Storybook stories are ES6 objects that return a β€œrenderable object.” Consider the following React story: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - In this case, the renderable object is the React element, `