CSF Factories: Add parameters/globals types, `extend` API, portable stories #30601

kasperpeulen · 2025-02-20T14:13:12Z

What I did

This adds a couple of points from this RFC:
#30112

Added typesafety for core parameters and globals, and a way to provide type information as addon.
Implement the extend API from the RFC
Portable story support for React

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

stories
unit tests
integration tests
end-to-end tests

Manual testing

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts
Make sure this PR contains one of the labels below:
Available labels
- bug: Internal changes that fixes incorrect behavior.
- maintenance: User-facing maintenance tasks.
- dependencies: Upgrading (sometimes downgrading) dependencies.
- build: Internal-facing build tooling & test updates. Will not show up in release changelog.
- cleanup: Minor cleanup style change. Will not show up in release changelog.
- documentation: Documentation only changes. Will not show up in release changelog.
- feature request: Introducing a new feature.
- BREAKING CHANGE: Changes that break compatibility in some way with current major version.
- other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-30601-sha-d70f67e1. Try it out in a new sandbox by running npx [email protected] sandbox or in an existing project with npx [email protected] upgrade.

More information


Published version	`0.0.0-pr-30601-sha-d70f67e1`
Triggered by	@kasperpeulen
Repository	storybookjs/storybook
Branch	`kasper/csf-parameters`
Commit	`d70f67e1`
Datetime	Tue Jul 8 08:28:05 UTC 2025 (`1751963285`)
Workflow run	16138049336

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=30601

name	before	after	diff	z	%
createSize	0 B	0 B	0 B	-	-
generateSize	79.6 MB	79.6 MB	0 B	-4.27	0%
initSize	79.6 MB	79.6 MB	0 B	-4.27	0%
diffSize	97 B	97 B	0 B	-	0%
buildSize	7.29 MB	7.31 MB	21.5 kB	0.25	0.3%
buildSbAddonsSize	1.9 MB	1.9 MB	156 B	Infinity	0%
buildSbCommonSize	195 kB	195 kB	0 B	-	0%
buildSbManagerSize	1.88 MB	1.88 MB	-4.69 kB	-0.82	-0.2%
buildSbPreviewSize	0 B	0 B	0 B	-	-
buildStaticSize	0 B	0 B	0 B	-	-
buildPrebuildSize	3.97 MB	3.97 MB	-4.53 kB	-0.75	-0.1%
buildPreviewSize	3.32 MB	3.34 MB	26 kB	0.41	0.8%
testBuildSize	0 B	0 B	0 B	-	-
testBuildSbAddonsSize	0 B	0 B	0 B	-	-
testBuildSbCommonSize	0 B	0 B	0 B	-	-
testBuildSbManagerSize	0 B	0 B	0 B	-	-
testBuildSbPreviewSize	0 B	0 B	0 B	-	-
testBuildStaticSize	0 B	0 B	0 B	-	-
testBuildPrebuildSize	0 B	0 B	0 B	-	-
testBuildPreviewSize	0 B	0 B	0 B	-	-

name	before	after	diff	z	%
createTime	10.2s	7.8s	-2s -424ms	-0.72	-31%
generateTime	22.6s	18.6s	-4s -4ms	-0.78	-21.5%
initTime	5.4s	4.6s	-756ms	-0.25	-16.1%
buildTime	11s	8.6s	-2s -470ms	-0.97	-28.6%
testBuildTime	0ms	0ms	0ms	-	-
devPreviewResponsive	5.5s	4.9s	-586ms	-0.55	-11.8%
devManagerResponsive	5.3s	4.7s	-634ms	-0.55	-13.4%
devManagerHeaderVisible	681ms	746ms	65ms	-0.21	8.7%
devManagerIndexVisible	691ms	803ms	112ms	0.13	13.9%
devStoryVisibleUncached	1.1s	1.8s	620ms	-0.02	34.2%
devStoryVisible	758ms	822ms	64ms	0.03	7.8%
devAutodocsVisible	674ms	790ms	116ms	0.34	14.7%
devMDXVisible	622ms	792ms	170ms	0.93	21.5%
buildManagerHeaderVisible	1.1s	778ms	-415ms	-0.17	-53.3%
buildManagerIndexVisible	1.2s	829ms	-447ms	-0.09	-53.9%
buildStoryVisible	1.1s	758ms	-416ms	-0.13	-54.9%
buildAutodocsVisible	1s	749ms	-327ms	0.87	-43.7%
buildMDXVisible	683ms	657ms	-26ms	0.44	-4%

Greptile Summary

Enhanced type safety across Storybook addons by introducing consistent parameter typing and addon definition patterns.

Replaced definePreview with definePreviewAddon from storybook/internal/csf for better type inference
Added new *Types interfaces (e.g. A11yTypes, ActionsTypes) to wrap parameters and globals for each addon
Made configuration parameters optional with ? modifier for better flexibility
Introduced PreviewAddon interface and InferTypes utility in csf-factories.ts for improved addon type safety
Updated Next.js framework integrations to support the new typesafe parameter system

# Conflicts: # code/core/src/csf/csf-factories.ts

nx-cloud · 2025-02-20T14:19:05Z

View your CI Pipeline Execution ↗ for commit d70f67e.

Command	Status	Duration	Result
`nx run-many -t build --parallel=3`	✅ Succeeded	1m 27s	View ↗

☁️ Nx Cloud last updated this comment at 2025-06-10 09:42:34 UTC

greptile-apps

_{37 file(s) reviewed, 14 comment(s)}
_{Edit PR Review Bot Settings | Greptile}

code/.storybook/preview.tsx

code/addons/backgrounds/src/index.ts

code/addons/essentials/src/types.ts

code/addons/highlight/src/types.ts

code/addons/interactions/src/index.ts

code/core/src/csf/csf-factories.test.ts

code/frameworks/nextjs/src/index.ts

code/frameworks/experimental-nextjs-vite/src/index.ts

code/renderers/react/src/preview.tsx

# Conflicts: # code/addons/a11y/src/index.ts # code/addons/a11y/src/types.ts # code/addons/actions/src/index.ts # code/addons/backgrounds/src/index.ts # code/addons/controls/src/index.ts # code/addons/docs/src/index.ts # code/addons/essentials/src/index.ts # code/addons/essentials/src/types.ts # code/addons/highlight/src/index.ts # code/addons/highlight/src/types.ts # code/addons/interactions/src/types.ts # code/addons/links/src/index.ts # code/addons/measure/src/index.ts # code/addons/outline/src/index.ts # code/addons/pseudo-states/src/index.ts # code/addons/test/src/index.ts # code/addons/test/src/types.ts # code/addons/themes/src/index.ts # code/addons/viewport/src/index.ts # code/core/src/backgrounds/types.ts # code/core/src/csf/csf-factories.ts # code/core/src/viewport/types.ts # code/frameworks/nextjs-vite/src/index.ts # code/frameworks/nextjs/src/index.ts # code/renderers/react/src/csf-factories.test.tsx # code/renderers/react/src/preview.tsx

storybook-pr-benchmarking · 2025-05-23T14:11:01Z

Package Benchmarks

^{Commit: d70f67e, ran on 10 June 2025 at 09:47:07 UTC}

The following packages have significant changes to their size or dependencies:

`storybook`

	Before	After	Difference
Dependency count	49	49	0
Self size	31.40 MB	31.22 MB	🎉 -185 KB 🎉
Dependency size	17.41 MB	17.41 MB	0 B
Bundle Size Analyzer	Link	Link

`sb`

	Before	After	Difference
Dependency count	50	50	0
Self size	1 KB	1 KB	0 B
Dependency size	48.81 MB	48.63 MB	🎉 -185 KB 🎉
Bundle Size Analyzer	Link	Link

`@storybook/cli`

	Before	After	Difference
Dependency count	324	324	0
Self size	244 KB	244 KB	🎉 -137 B 🎉
Dependency size	97.90 MB	98.82 MB	🚨 +920 KB 🚨
Bundle Size Analyzer	Link	Link

`@storybook/codemod`

	Before	After	Difference
Dependency count	267	267	0
Self size	31 KB	31 KB	0 B
Dependency size	82.29 MB	82.11 MB	🎉 -185 KB 🎉
Bundle Size Analyzer	Link	Link

`create-storybook`

	Before	After	Difference
Dependency count	1	1	0
Self size	11.02 MB	12.13 MB	🚨 +1.11 MB 🚨
Dependency size	98 KB	98 KB	0 B
Bundle Size Analyzer	Link	Link

code/frameworks/nextjs-vite/src/index.ts

# Conflicts: # code/addons/vitest/src/types.ts

kasperpeulen · 2025-06-06T15:30:00Z

code/core/src/csf/csf-factories.ts

+}
+
+export type InferTypes<T extends PreviewAddon<never>[]> = T extends PreviewAddon<infer C>[]
+  ? C & { csf4: true }


csf: number

kasperpeulen · 2025-06-06T15:38:10Z

code/renderers/react/src/csf-factories.test.tsx

+      },
+    });
+
+    await Basic.play(meta.input as any);


shilman

Looks good except for a few minor comments e.g. csf: versionNumber instead of csf4: true. Let's get @kylegach to look at the docs changes, but those look good to me too! Great job @kasperpeulen !!!!

mrginglymus · 2025-06-08T14:49:37Z

Thanks for all the work on this @kasperpeulen! I'm trying the canary, and it's let me remove at least one @ts-expect-error so far :)

I have a preview with:

definePreview({
  parameters: {
    docs: {
      canvas: {
        sourceState: 'shown',
      }
    }
  }
});

and it's complaining that:

TS2741: Property of is missing in type { sourceState: "shown"; } but required in type CanvasBlockParameters

I'm also getting a couple of errors from within react/preview.d.ts;

.yarn/__virtual__/@storybook-react-virtual-f18c64b3e5/2/.yarn/berry/cache/@storybook-react-npm-0.0.0-pr-30601-sha-7dd57361-acfe016f2d-10c0.zip/node_modules/@storybook/react/dist/preview.d.ts:177:11 - error TS2430: Interface 'ReactPreview<T>' incorrectly extends interface 'Preview<ReactTypes & T>'.
  Types of property 'meta' are incompatible.
    ....
                            Types of property 'args' are incompatible.
                              Type 'unknown' is not assignable to type 'TArgs'.
                                'TArgs' could be instantiated with an arbitrary type which could be unrelated to 'unknown'.

177 interface ReactPreview<T extends AddonTypes> extends Preview<ReactTypes & T> {
              ~~~~~~~~~~~~

.yarn/__virtual__/@storybook-react-virtual-f18c64b3e5/2/.yarn/berry/cache/@storybook-react-npm-0.0.0-pr-30601-sha-7dd57361-acfe016f2d-10c0.zip/node_modules/@storybook/react/dist/preview.d.ts:196:195 - error TS2344: Type 'TInput' does not satisfy the constraint 'StoryAnnotations<T, T["args"]>'.
     ....
                                                                      Type 'T["args"]' is not assignable to type 'AddMocks<T["args"], MetaInput["args"]>'.

196     story<TInput extends Simplify<StoryAnnotations<T, AddMocks<T['args'], MetaInput['args']>, SetOptional<T['args'], keyof T['args'] & keyof MetaInput['args']>>>>(story?: TInput): ReactStory<T, TInput>;

It seems like tsup is eating the @ts-expect-error that's in the source.

# Conflicts: # docs/api/csf/csf-factories.mdx

kasperpeulen · 2025-06-10T09:37:26Z

@mrginglymus Fixed the docs types, thanks!

I'm gonna look how to configure tsup to keep the comments, but for now I would recommend turning on skipLibCheck.

mrginglymus · 2025-06-10T10:39:37Z

Thanks!

I'm gonna look how to configure tsup to keep the comments, but for now I would recommend turning on skipLibCheck.

Unfortunately I have my own locally crafted .d.ts files that need type checking, so I can't enable skipLibCheck. I'll just patch the expect-errors back in for now :)

If you do succeed, it'd be a great help on #31555, where that's the last remaining hurdle; preserving the ts-expect-errors.

kasperpeulen · 2025-06-11T06:43:57Z

@mrginglymus This is an interesting read from Matt Pocock:

I've changed my mind on .d.ts files.
If you're writing application code, you should NEVER use them.
Let me explain 🧵
https://x.com/mattpocockuk/status/1820454283457765645

mrginglymus · 2025-06-11T09:56:17Z

It's an interesting approach, but after a quick play looks like it'll have too many unwanted side effects that would need dealing with (e.g. removing the stub files from the compiled code), as well as obfuscating their intent.

On the whole I don't mind the burden of dealing with downstream type errors; they're usually trivial but ocassionaly point at an underlying problem that's worth fixing.

storybook-bot · 2025-07-08T08:54:32Z

Failed to publish canary version of this pull request, triggered by @kasperpeulen. See the failed workflow run at: https://github.com/storybookjs/storybook/actions/runs/16138593936

storybook-bot · 2025-07-10T12:53:14Z

Failed to publish canary version of this pull request, triggered by @kasperpeulen. See the failed workflow run at: https://github.com/storybookjs/storybook/actions/runs/16195630556

kasperpeulen added 3 commits February 12, 2025 13:58

WIP: Add support for parameters

57c2c8c

Merge remote-tracking branch 'origin/next' into kasper/csf-parameters

cf87f2a

# Conflicts: # code/core/src/csf/csf-factories.ts

Fix

59b9d5d

greptile-apps bot reviewed Feb 20, 2025

View reviewed changes

Rollback preview changes

526ce10

kasperpeulen added ci:normal feature request labels Feb 20, 2025

mrginglymus reviewed Feb 24, 2025

View reviewed changes

code/renderers/react/src/preview.tsx Outdated Show resolved Hide resolved

kasperpeulen added ci:normal and removed ci:normal labels Feb 24, 2025

valentinpalkovic force-pushed the kasper/csf-parameters branch from 3f0aa55 to 526ce10 Compare February 24, 2025 13:09

valentinpalkovic assigned kasperpeulen Feb 24, 2025

kasperpeulen added 8 commits February 24, 2025 15:45

Fix tests

07fbadc

Pass parameters to story and meta

ec29949

Fix type tests

238df1b

Don't export in addon-outline

8050a06

Don't export in addon-backgrounds

f7a85a7

Get all addons in shape

793a49b

Fix next as well

5af7f47

kasperpeulen added 2 commits May 25, 2025 15:42

Fix check

70c0641

Just test the parameters

9eb7abe

kasperpeulen commented May 26, 2025

View reviewed changes

code/frameworks/nextjs-vite/src/index.ts Outdated Show resolved Hide resolved

kasperpeulen added 5 commits May 26, 2025 14:09

Fix

9733393

Merge remote-tracking branch 'origin/next' into kasper/csf-parameters

e77a51f

# Conflicts: # code/addons/vitest/src/types.ts

Remove shared csf4 file

1e25c44

Restructure core annotations in csf export

e8fbce4

Fix check

bfc9665

kasperpeulen commented Jun 6, 2025

View reviewed changes

code/renderers/react/src/csf-factories.test.tsx Outdated

},

});

await Basic.play(meta.input as any);

Copy link

Contributor Author

kasperpeulen Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check this

shilman changed the title ~~CSF: Typesafe parameters and globals, extension API and portable stories support for CSF factories~~ CSF Factoroies: Typesafe parameters and globals, extend, automatic portable stories Jun 6, 2025

shilman changed the title ~~CSF Factoroies: Typesafe parameters and globals, extend, automatic portable stories~~ CSF Factoroies: Typesafe parameters/globals, extend API, portable stories Jun 6, 2025

shilman changed the title ~~CSF Factoroies: Typesafe parameters/globals, extend API, portable stories~~ CSF Factories: Typesafe parameters/globals, extend API, portable stories Jun 6, 2025

shilman approved these changes Jun 6, 2025

View reviewed changes

shilman added the csf label Jun 6, 2025

shilman changed the title ~~CSF Factories: Typesafe parameters/globals, extend API, portable stories~~ CSF Factories: Add parameters/globals types, extend API, portable stories Jun 6, 2025

kasperpeulen added 3 commits June 10, 2025 11:32

Address feedback

9c22424

Merge remote-tracking branch 'origin/next' into kasper/csf-parameters

9ab9f8b

# Conflicts: # docs/api/csf/csf-factories.mdx

Roll back docs changes

d70f67e

kasperpeulen merged commit fc8890b into next Jun 10, 2025
56 of 57 checks passed

kasperpeulen deleted the kasper/csf-parameters branch June 10, 2025 09:56

kasperpeulen mentioned this pull request Jun 10, 2025

[Tracking]: Feedback-ready CSF Factories for React #31530

Closed

21 tasks

github-actions bot mentioned this pull request Jun 10, 2025

Release: Prerelease 9.1.0-alpha.4 #31725

Merged

4 tasks

kasperpeulen mentioned this pull request Jun 10, 2025

CSF: Add run and play function in csf factory #30648

Closed

8 tasks

github-actions bot mentioned this pull request Aug 13, 2025

[master] Michijs Dependabot changes michijs/michijs-storybook-template#68

Closed

dosubot bot mentioned this pull request Aug 20, 2025

[Bug]: CSF-Factories: Does not infer types from global decorators #32307

Open

Uh oh!

CSF Factories: Add parameters/globals types, extend API, portable stories #30601

CSF Factories: Add parameters/globals types, extend API, portable stories #30601

Uh oh!

Conversation

kasperpeulen commented Feb 20, 2025 • edited by storybook-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Greptile Summary

Uh oh!

nx-cloud bot commented Feb 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

storybook-pr-benchmarking bot commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Benchmarks

storybook

sb

@storybook/cli

@storybook/codemod

create-storybook

Uh oh!

Uh oh!

kasperpeulen Jun 6, 2025

Choose a reason for hiding this comment

Uh oh!

kasperpeulen Jun 6, 2025

Choose a reason for hiding this comment

Uh oh!

shilman left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrginglymus commented Jun 8, 2025

Uh oh!

kasperpeulen commented Jun 10, 2025

Uh oh!

Uh oh!

mrginglymus commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kasperpeulen commented Jun 11, 2025

Uh oh!

mrginglymus commented Jun 11, 2025

Uh oh!

storybook-bot commented Jul 8, 2025

Uh oh!

storybook-bot commented Jul 10, 2025

Uh oh!

Uh oh!

CSF Factories: Add parameters/globals types, `extend` API, portable stories #30601

CSF Factories: Add parameters/globals types, `extend` API, portable stories #30601

kasperpeulen commented Feb 20, 2025 •

edited by storybook-bot

Loading

nx-cloud bot commented Feb 20, 2025 •

edited

Loading

storybook-pr-benchmarking bot commented May 23, 2025 •

edited

Loading

`storybook`

`sb`

`@storybook/cli`

`@storybook/codemod`

`create-storybook`

shilman left a comment •

edited

Loading

mrginglymus commented Jun 10, 2025 •

edited

Loading