Docs: Add CSF factory API documentation #30343
Conversation
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
10 file(s) reviewed, 12 comment(s)
Edit PR Review Bot Settings | Greptile
| const Secondary = meta.story({ | ||
| args: { | ||
| // 👇 Access args from another story using its `composed` property | ||
| ...Primary.composed.args, |
There was a problem hiding this comment.
logic: spreading Primary.composed.args and then overriding label with the same value ('Button') appears redundant since it's the same as the Primary story
| const Primary = meta.story({ | ||
| args: { | ||
| label: 'Button', | ||
| }, | ||
| }); |
There was a problem hiding this comment.
style: consider adding export statements to make these stories available to Storybook
| const Primary = meta.story({ | ||
| args: { | ||
| label: 'Button', | ||
| }, | ||
| }); |
There was a problem hiding this comment.
logic: Primary story should be exported to be visible in Storybook
docs/api/csf.mdx
Outdated
| import preview from '../../../.storybook/preview'; | ||
| ``` | ||
|
|
||
| For more details, refer to the [subpath imports documentation](../writing-stories/mocking-modules#subpath-imports). |
There was a problem hiding this comment.
syntax: The link to subpath imports documentation is incorrect. The URL should be ../writing-stories/mocking-modules.mdx#subpath-imports (missing .mdx extension)
| <Callout variant="warning"> | ||
| If you are using the CSF Factory format, you don't need to use the portable stories API. Instead, you can use the [CSF Factory API](../../api/csf.mdx). | ||
| </Callout> |
There was a problem hiding this comment.
style: link to CSF Factory API should be more specific - consider linking directly to the CSF Factory section of the CSF documentation
|
View your CI Pipeline Execution ↗ for commit a9eaf38.
☁️ Nx Cloud last updated this comment at |
| addons: [addonTest()], | ||
| parameters: { | ||
| // type-safe! | ||
| layout: 'fullscreen', |
There was a problem hiding this comment.
In our solution the expected behavior would be:
- Users would always get autocompletion/type safety for Storybook core parameters like layout
- Users would get autocompletion/type safety for an addon's parameters if the addon has types and uses the new implementation
- Users would not get autocompletion/type safety if the addon is using the legacy format
Not sure where to mention but it would be nice to mention that, for instance in this use case the user would have test as a parameter in their autocompletion
There was a problem hiding this comment.
ah nevermind I see that it's mentioned above the usage of this snippet (though it sort of seems like layout is the autocompleted property coming from using addon test)
| }); | ||
|
|
||
| test('renders primary button with overridden props', async () => { | ||
| // You can override props by passing them in the context argument of the play function |
There was a problem hiding this comment.
| // You can override props by passing them in the context argument of the play function | |
| // You can override props by passing them directly to the story's component |
| const { Primary, Secondary } = stories; | ||
|
|
||
| test('renders primary button with default args', async () => { | ||
| // The run function will mount the componetn and run all of Storybook's lifecycle hooks |
There was a problem hiding this comment.
| // The run function will mount the componetn and run all of Storybook's lifecycle hooks | |
| // The run function will mount the component and run all of Storybook's lifecycle hooks |
| <CodeSnippets path="csf-factories-main-example.md" /> | ||
| {/* prettier-ignore-end */} | ||
|
|
||
| ### `definePreview` |
There was a problem hiding this comment.
would it make sense to mention in this section that now the preview object will be used to define meta/stories, to anticipate that users will have to import it in every story file?
|
|
||
| ## Upgrading from CSF 3 | ||
|
|
||
| You can upgrade your project's story files to CSF Factories incrementally or all at once. However, you must upgrade your `.storybook/main.ts` and `.storybook/preview.ts` files first before you can use CSF Factories in a story file. |
There was a problem hiding this comment.
FYI the main file doesn't really have anything to do with csf factory, it's just a type helper that follows the define pattern. Though not needed, it's a good thing to have users migrate to the new format anyway!
| <Callout variant="info"> | ||
| If your story files are not using CSF 3 already, please run `npx storybook migrate csf-2-to-3` to automatically upgrade your project from CSF 2 to CSF 3. | ||
|
|
||
| You can also [migrate manually](./index.mdx#upgrading-from-csf-2-to-csf-3). | ||
| </Callout> |
There was a problem hiding this comment.
We can now change/remove this section! The codemod will also migrate from CSF 2 to 3.
|
|
||
| ## Overview | ||
|
|
||
| The CSF Factories API is composed of four main functions to help you write stories. Note how the functions operate as a factory, each producing the next function in the chain (`definePreview` → `preview.meta` → `meta.story`), providing full type safety at each step. |
There was a problem hiding this comment.
| The CSF Factories API is composed of four main functions to help you write stories. Note how the functions operate as a factory, each producing the next function in the chain (`definePreview` → `preview.meta` → `meta.story`), providing full type safety at each step. | |
| The CSF Factories API is composed of three main functions to help you write stories. Note how the functions operate as factories, each producing the next function in the chain (`definePreview` → `preview.meta` → `meta.story`), providing full type safety at each step. |
| - [Migrates `.storybook/preview.js`](#3-update-your-preview-config-file) | ||
| - Converts all story files to [use CSF Factories](#4-update-your-story-files) | ||
|
|
||
| This should get you started with CSF Factories immediately. If you prefer a manual migration, the next sections detail the neccessary updates. |
There was a problem hiding this comment.
| This should get you started with CSF Factories immediately. If you prefer a manual migration, the next sections detail the neccessary updates. | |
| This should get you started with CSF Factories immediately. If you prefer a manual migration, the next sections detail the necessary updates. |
|
|
||
| ### Will I have to migrate all of my stories to this new format? | ||
|
|
||
| Storybook will continue to support CSF 1, [CSF 2](../../../release-6-5/docs/api/stories/csf.mdx), and [CSF 3](./index.mdx) for the foreseeable future. None of these prior formats are deprecated. |
There was a problem hiding this comment.
| Storybook will continue to support CSF 1, [CSF 2](../../../release-6-5/docs/api/stories/csf.mdx), and [CSF 3](./index.mdx) for the foreseeable future. None of these prior formats are deprecated. | |
| Storybook will continue to support CSF 1, [CSF 2](../../../release-6-5/docs/api/stories/csf.mdx), and [CSF 3](./index.mdx) for the foreseeable future. None of these prior formats is deprecated. |
| "#.storybook/preview": { | ||
| "default": "./.storybook/preview.ts", | ||
| }, | ||
| "#*": ["./*", "./*.ts", "./*.tsx"], |
There was a problem hiding this comment.
Interesting 🤔 the codemod only adds "#*": ["./*", "./*.ts", "./*.tsx"] and assumes that users will write #.storybook/preview which will relate to <root>.storybook/preview and if they have the preview file somewhere else, they will have to adjust the import in each file to something like #some-dir/.storybook/preview.
This means users with multiple Storybooks could have multiple imports like #apps/.storybook/preview and #libs/.storybook/preview without having to change anything in their package.json.
Perhaps the codemod should set this more specific field like what Kyle wrote here instead? WDYT @kasperpeulen?
|
|
||
| ```diff title=".storybook/preview.ts" | ||
| // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, experimental-nextjs-vite) | ||
| + import { definePreview } from '@storybook/your-framework/node'; |
There was a problem hiding this comment.
| + import { definePreview } from '@storybook/your-framework/node'; | |
| + import { definePreview } from '@storybook/your-framework'; |
| + import { definePreview } from '@storybook/your-framework/node'; | ||
| - import { Preview } from '@storybook/your-renderer'; | ||
| // 👇 Import the addons you are using | ||
| + import addonTest from '@storybook/experimental-addon-test'; |
There was a problem hiding this comment.
This part is quite tricky. Our core addons will be a function, a default export and part of the root entrypoint. Older addons will not have that format, the addon-kit also doesn't have that format (yet). The codemod will figure everything out to fill things properly, with this logic:
- Is it a core addon? Does it contain (./preview) annotations? Then it's default imported as a function
- If not a core addon, does it contain annotations? Then it's namespace imported as object
So in this scenario:
// .storybook/main
export default {
addons: [
'@storybook/addon-onboarding', // core addon, without annotations - then it's ignored
'@storybook/experimental-addon-test', // core addon, with annotations
'storybook-addon-designs', // non-core addon, without annotations - then it's ignored
'storybook-addon-performance', // non-core addon, with annotations
]
}the preview file would become:
// .storybook/preview
import { definePreview } from '@storybook/your-framework';
import experimentalAddonTest from '@storybook/experimental-addon-test';
import * as storybookAddonPerformance from 'storybook-addon-performance/preview';
export default definePreview({
addons: [
experimentalAddonTest(),
storybookAddonPerformance,
],
});There was a problem hiding this comment.
In the future hopefully all addons will use the same format with functions, but it will be difficult to enforce that. There will be a long transition period from the older format to the new one
| ``` | ||
|
|
||
| <Callout variant="info"> | ||
| The property name "composed" was chosen because the values within are composed from the story, its component meta, and the preview configuration. |
There was a problem hiding this comment.
btw the codemod will also change story files like this and will use .input instead of .composed. I'm assuming that users who originally wrote MyStory.args are expecting to see the args that they wrote in the story, not the composed ones coming from preview/meta as well. Though I'd say it's more valuable to get the composed ones!
|
|
||
| While using CSF Factories, you can still use the older formats, as long as they are not mixed in the same file. If you want to migrate your existing files to the new format, refer to [the upgrade section](#upgrading-from-csf-3), above. | ||
|
|
||
| ### How can I know more about this format and provide feedback? |
There was a problem hiding this comment.
Perhaps we add one more:
### Will this format work with docs(.mdx) pages?
Yes, the docs blocks support the CSF factory format and you wouldn't have to change the code in your mdx files.
Closes #30342
Closes #30329
What I did
This PR introduces documentation for the CSF Factory format.
Checklist for Contributors
Testing
Manual testing
sync-docsinstorybookjs/weblocallymain, so the page-level tabs show upDocumentation
MIGRATION.MD
Checklist for Maintainers
When this PR is ready for testing, make sure to add
ci:normal,ci:mergedorci:dailyGH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found incode/lib/cli-storybook/src/sandbox-templates.tsMake 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 introduces comprehensive documentation for the new CSF Factory API, providing examples and guidelines for creating and testing Storybook stories with improved type safety and reusability.
defineMainanddefinePreviewconfiguration examples indocs/_snippets/csf-factories-main-example.mdanddocs/_snippets/csf-factories-preview-example.mdpreview.meta()andmeta.story()indocs/_snippets/csf-factories-story-example.mddocs/_snippets/portable-stories-csf-factory-run.mdcomposedproperty