Docs: Update CSF Next API reference by kylegach · Pull Request #32341 · storybookjs/storybook

kylegach · 2025-08-27T23:11:17Z

What I did

Tip

Reviewers may wish to compare the original CSF Factories API reference to this one, for reference.

Rename from CSF Factories to CSF Next
Reduce subpath import promotion
- Remove from snippets
- Add callout instructing how to set them up (for builder aliases, too)
Add automatic upgrade instructions
Add Story.extend

Checklist for Contributors

Testing

Manual testing

Sync this branch with locally running docs site

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.

Greptile Summary

This PR represents a significant evolution in Storybook's Component Story Format (CSF) documentation, transitioning from the experimental "CSF Factories" to the more mature "CSF Next" API. The changes include:

Core Documentation Updates:

Complete removal of the minimal csf-factories.mdx file and replacement with comprehensive csf-next.mdx documentation
Renaming from "CSF Factories" to "CSF Next" throughout the documentation to better position this as the next iteration of CSF
Addition of extensive API reference covering defineMain, definePreview, preview.meta, and meta.story factory functions

Enhanced Migration Support:

Introduction of automatic upgrade instructions via storybook automigrate csf-factories command across npm, pnpm, and yarn
Comprehensive manual migration guide with before/after code examples
Addition of new Story.extend method documentation for extending existing stories

Developer Experience Improvements:

Creation of builder alias configuration examples for both Vite and Webpack
Reduced promotion of subpath imports in favor of proper alias setup
Clear callouts about React-only support and experimental/preview status
FAQ section addressing common migration concerns

The documentation follows Storybook's established patterns with conditional rendering for React-only content, proper package manager variants, and extensive code examples. This change represents the maturation of CSF from experimental factory functions to a production-ready API that provides full type safety for Storybook stories.

Confidence score: 4/5

This documentation-only PR is generally safe to merge with well-structured content and clear migration guidance
Score reflects the comprehensive nature of the changes and potential for improved user experience, though some minor inconsistencies exist
Pay attention to the automigrate command naming in csf-factories-automigrate.md which may need alignment with the CSF Next rebrand

- Rename from CSF Factories to CSF Next - Add automatic upgrade instructions - Add Story.extend

greptile-apps

_{4 files reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

nx-cloud · 2025-08-27T23:18:32Z

View your CI Pipeline Execution ↗ for commit 1c974fe

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

☁️ Nx Cloud last updated this comment at 2025-08-28 21:14:44 UTC

shilman

Great job!! Minor comments.

shilman · 2025-08-28T01:52:06Z

+<details>
+<summary>Builder alias</summary>
+
+You can configure aliases for your builder (Vite or Webpack) in your main Storybook configuration, like so:


we should verify that when you use builder aliases does our static analysis still works (I think it does because it's hard-coded, but we should double check).

@kasperpeulen ?

I don't know, we should test this @yannbf @ghengeveld
But why are we recommending builder aliases?
I belief this snippet is not complete, they should also change their tsconfig.json.

If they are already using builder aliases, they can use/read whatever is recommended by their framework for that.
If they are not, let's recommend a standard instead.

Good call, Kasper. I deprioritized builder aliases here.

shilman · 2025-08-28T01:58:08Z

+
+#### `<StoryName>.extend`
+
+You can use the `.extend` method to create a new story based on an existing one, with the option to override or add new properties. Objects will be deep-merged; arrays and other primitives will be replaced.


Deep-merged is an oversimplification. I believe that Args get shallow-merged. Parameters are deep-merged except for arrays which get replaced. Tags concatenate. Decorators concatenate. We should document each one of these in their respective docs (e.g. args docs) and potentially have a canonical section somewhere about data merging, which summarizes those things and then reference that section here. Or maybe this is the canonical section.

I like the ideas here, but I'll have to do that in a future effort. For now, I've added more clarity here.

shilman · 2025-08-28T02:06:14Z

+
+**4. Update your Vitest setup file**
+
+If you're using [Storybook's Vitest addon](../../writing-tests/integrations/vitest-addon.mdx), you can remove your Vitest setup file.


They might have other setup stuff in there that they don't want to remove. I guess users will figure this out on their own, but perhaps there is a way to phrase it better.

I clarified which setup file we're talking about. It seems very unlikely they're using the Storybook-specific setup file for anything else?

+ ...you can remove your Vitest setup file (`.storybook/vitest.setup.ts`). - ...you can remove your Vitest setup file.

Co-authored-by: Michael Shilman <shilman@users.noreply.github.com>

- Clean up weird applied suggestions from last commit - Add details about Story.extend's property merging - Clarify that CSF Next does not have to be used for all story files - Clarify Vitest setup file needs

* next: add kiro steering docs

- Deprioritize builder aliases

* next: (23 commits) Bump version from "10.0.0-beta.1" to "10.0.0-beta.2" [skip ci] Write changelog for 10.0.0-beta.2 [skip ci] Refactor: Use fileURLToPath for module resolution in Next.js Vite preset fix typo Update CHANGELOG.md for v9.1.4 [skip ci] Bump version from "10.0.0-beta.0" to "10.0.0-beta.1" [skip ci] Write changelog for 10.0.0-beta.1 [skip ci] Fix dts bundling external detection Tags: Remove unodocumented x-only tags Update e2e tests Replace icons Update stories Reset invert toggle when clearing filters Add invert filter toggle and visual separator between user tags and built-in tags Update dependencies and ESLint configuration Refactor extract.ts to use internal parser for Babel code parsing fix z-index on mobile and write e2e tests Fix postinstall script to handle Playwright installation errors gracefully test(angular): fix framework-cli test cases Add story count indicator to tags filter ...

Docs: Update CSF Next API reference (cherry picked from commit e0a8d9b)

Docs: Update CSF Next API reference

5f725be

- Rename from CSF Factories to CSF Next - Add automatic upgrade instructions - Add Story.extend

kylegach self-assigned this Aug 27, 2025

kylegach requested a review from jonniebigodes as a code owner August 27, 2025 23:11

kylegach added documentation ci:docs Run the CI jobs for documentation checks only. patch:yes Bugfix & documentation PR that need to be picked to main branch labels Aug 27, 2025

greptile-apps Bot reviewed Aug 27, 2025

View reviewed changes

shilman approved these changes Aug 28, 2025

View reviewed changes

kylegach commented Aug 28, 2025

View reviewed changes

Comment thread docs/api/csf/csf-next.mdx Outdated

kylegach and others added 5 commits August 28, 2025 13:36

Apply suggestions from code review

74c0733

Co-authored-by: Michael Shilman <shilman@users.noreply.github.com>

Address feedback

7aa0075

- Clean up weird applied suggestions from last commit - Add details about Story.extend's property merging - Clarify that CSF Next does not have to be used for all story files - Clarify Vitest setup file needs

Merge branch 'next' into docs-csf-next

1c974fe

* next: add kiro steering docs

Address feedback

44e82ee

- Deprioritize builder aliases

kylegach merged commit e0a8d9b into next Sep 3, 2025
5 checks passed

kylegach deleted the docs-csf-next branch September 3, 2025 16:23

This was referenced Sep 3, 2025

Release: Patch 9.1.5 #32390

Merged

Release: Prerelease 10.0.0-beta.3 #32408

Merged

shilman pushed a commit that referenced this pull request Sep 6, 2025

Merge pull request #32341 from storybookjs/docs-csf-next

4aaaeba

Docs: Update CSF Next API reference (cherry picked from commit e0a8d9b)

github-actions Bot added the patch:done Patch/release PRs already cherry-picked to main/release branch label Sep 6, 2025

github-actions Bot mentioned this pull request Sep 16, 2025

Release: Prerelease 10.0.0-beta.3 #32473

Closed

23 tasks

ndelangen removed the patch:yes Bugfix & documentation PR that need to be picked to main branch label Oct 28, 2025

coderabbitai Bot mentioned this pull request Mar 28, 2026

[Feat] #74 - 공통 Empty States 컴포넌트 추가 ajou-industry-matching/aim-frontend#76

Merged

5 tasks


		#### `<StoryName>.extend`

		You can use the `.extend` method to create a new story based on an existing one, with the option to override or add new properties. Objects will be deep-merged; arrays and other primitives will be replaced.


		4. Update your Vitest setup file

		If you're using [Storybook's Vitest addon](../../writing-tests/integrations/vitest-addon.mdx), you can remove your Vitest setup file.

Uh oh!

Conversation

kylegach commented Aug 27, 2025 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Checklist for Contributors

Testing

Manual testing

Documentation

Checklist for Maintainers

Greptile Summary

Confidence score: 4/5

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

nx-cloud Bot commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shilman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kylegach commented Aug 27, 2025 •

edited by greptile-apps Bot

Loading

nx-cloud Bot commented Aug 27, 2025 •

edited

Loading