Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Framework documentation updates #22272

Open
kylegach opened this issue Apr 26, 2023 · 1 comment
Open

Framework documentation updates #22272

kylegach opened this issue Apr 26, 2023 · 1 comment

Comments

@kylegach
Copy link
Contributor

Per the 7.0 changes, we introduced a new piece of documentation providing some guidance on how to build a Storybook framework. This was mostly based on the work done to create the NextJS framework. However, we've run into a situation where we should complement it with a more technically oriented piece of documentation to allow users not only to learn the actual steps on how to build a community framework but also tie it up to other parts of Storybook, including the CLI and the templates provided as they serve as the first point of contact for users when they install it for the framework.

This issue sparked from Ian VanSchooten's commented here.

@kylegach
Copy link
Contributor Author

kylegach commented May 9, 2023

From someone on Discord who created their own framework (for Docusaurus):

Sure thing! Generally it was pretty straightforward to implement this because I was converting my existing preset Addon, and so it was just a matter of figuring out how to move it all over to the new system. You might even argue that it wasn't necessary for this to become a Framework, but the ability to provide configuration options was a good selling point.

Anyhow, some thoughts...

One of my first stumbling blocks was understanding how I could leverage an existing framework when building my own. Since Docusaurus is built on React, I knew I didn't want to reinvent the wheel and would use the existing Framework written for React, but I didn't know how to do this or if it was really something you should do. So I posted in this Discord (https://discord.com/channels/486522875931656193/1079505344042111086) and was pretty quickly pointed to some existing work. I think some documentation around this would be ideal, since you're bound to have a bunch of derivative Frameworks.

Also, a note on extending @storybook/react-webpack5 - nowhere, at least as far as I can tell, does this package indicate the configuration options? I was able to dig into the TS def and see fastRefresh, strictMode, legacyRootApi, etc. but I would expect these to be listed somewhere in the docs as well. I might just not be seeing it though.

Finally, the biggest help (and sometimes only way to figure something out) for me in developing this was excellent types. For example, even though you get warned that config is deprecated and you should use previewAnnotations, I wasn't able to find clear documentation on why it changed, the differences between the two, and if there was anything different about this new export (beyond this one-liner https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#config-preset-entry-replaced-with-previewannotations), so StorybookConfig["previewAnnotations"] type was super helpful in at least ensuring I understood the return type.

I'll just quickly note that I'm usually not the best at finding and understanding documentation, so it's possible I just totally missed it for some of these.

Oh actually one more bit where I struggled: I needed to access the options provided to the Framework, but couldn't find docs for that, so I was able to look at the existing react-webpack5 Framework and saw that it was const config = await options.presets.apply<StorybookConfig['framework']>('framework'); - still not entirely sure if I know what's going on in this, but it worked

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Backlog
Development

No branches or pull requests

1 participant