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

Source: Support async parameters.docs.source.transform #30426

Open
wants to merge 12 commits into
base: next
Choose a base branch
from

Conversation

valentinpalkovic
Copy link
Contributor

@valentinpalkovic valentinpalkovic commented Jan 30, 2025

Closes #24236
Closes #23703

What I did

  • Added support to pass an async function to parameters.docs.source.transform
  • Deprecated parameters.docs.source.format

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 PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

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

name before after diff z %
createSize 0 B 0 B 0 B - -
generateSize 80.6 MB 80.6 MB 0 B 1.81 0%
initSize 80.6 MB 80.6 MB 0 B 1.81 0%
diffSize 97 B 97 B 0 B - 0%
buildSize 7.31 MB 7.26 MB -57.3 kB -289.23 -0.8%
buildSbAddonsSize 1.9 MB 1.87 MB -23.6 kB -198.85 -1.3%
buildSbCommonSize 195 kB 195 kB 0 B - 0%
buildSbManagerSize 1.88 MB 1.88 MB 6.9 kB 25.41 0.4%
buildSbPreviewSize 0 B 0 B 0 B - -
buildStaticSize 0 B 0 B 0 B - -
buildPrebuildSize 3.97 MB 3.95 MB -16.7 kB -96.21 -0.4%
buildPreviewSize 3.34 MB 3.3 MB -40.6 kB -966.18 -1.2%
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 6.6s 21.5s 14.9s 1.55 🔺69%
generateTime 17s 19.7s 2.6s -0.22 13.6%
initTime 4.2s 4.8s 599ms 0.33 12.3%
buildTime 9.1s 9.3s 215ms 0 2.3%
testBuildTime 0ms 0ms 0ms - -
devPreviewResponsive 5s 5.9s 823ms 0.42 13.9%
devManagerResponsive 4.8s 4.2s -643ms -0.69 -15.3%
devManagerHeaderVisible 776ms 971ms 195ms 2.2 🔺20.1%
devManagerIndexVisible 789ms 1s 230ms 2.39 🔺22.6%
devStoryVisibleUncached 1.7s 4.2s 2.4s 1.93 🔺58.6%
devStoryVisible 816ms 1s 200ms 2.24 🔺19.7%
devAutodocsVisible 681ms 897ms 216ms 1.42 🔺24.1%
devMDXVisible 761ms 912ms 151ms 2.32 🔺16.6%
buildManagerHeaderVisible 876ms 889ms 13ms 0.74 1.5%
buildManagerIndexVisible 888ms 993ms 105ms 1.19 10.6%
buildStoryVisible 830ms 792ms -38ms 0.31 -4.8%
buildAutodocsVisible 758ms 732ms -26ms 1.46 -3.6%
buildMDXVisible 563ms 671ms 108ms 0.6 16.1%

Greptile Summary

Added support for asynchronous source code transformation in Storybook's Source Doc Block, allowing dynamic code processing with async functions while deprecating the format parameter.

  • Added async support to parameters.docs.source.transform in code/lib/blocks/src/blocks/Source.tsx using React hooks
  • Added new AsyncTransform example in code/addons/docs/template/stories/docspage/source.stories.ts demonstrating async usage
  • Deprecated parameters.docs.source.format parameter in favor of custom transformers in docs/api/doc-blocks/doc-block-source.mdx
  • Updated documentation in code/addons/docs/docs/recipes.md with async transform examples and migration guidance

Copy link

nx-cloud bot commented Jan 30, 2025

View your CI Pipeline Execution ↗ for commit 3434620.

Command Status Duration Result
nx run-many -t build -c production --parallel=3 ✅ Succeeded 3m 33s View ↗
nx affected -t check -c production --parallel=7 ✅ Succeeded <1s View ↗

☁️ Nx Cloud last updated this comment at 2025-02-23 19:44:41 UTC

@storybook-pr-benchmarking
Copy link

storybook-pr-benchmarking bot commented Jan 30, 2025

Package Benchmarks

Commit: 3434620, ran on 23 February 2025 at 19:52:42 UTC

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

@storybook/addon-a11y

Before After Difference
Dependency count 54 56 🚨 +2 🚨
Self size 445 KB 332 KB 🎉 -112 KB 🎉
Dependency size 12.47 MB 12.72 MB 🚨 +249 KB 🚨
Bundle Size Analyzer Link Link

@storybook/addon-backgrounds

Before After Difference
Dependency count 4 4 0
Self size 45 KB 27 KB 🎉 -18 KB 🎉
Dependency size 99 KB 99 KB 🚨 +3 B 🚨
Bundle Size Analyzer Link Link

@storybook/addon-docs

Before After Difference
Dependency count 13 15 🚨 +2 🚨
Self size 2.25 MB 2.26 MB 🚨 +7 KB 🚨
Dependency size 9.43 MB 9.67 MB 🚨 +235 KB 🚨
Bundle Size Analyzer Link Link

@storybook/addon-essentials

Before After Difference
Dependency count 32 34 🚨 +2 🚨
Self size 18 KB 12 KB 🎉 -6 KB 🎉
Dependency size 15.53 MB 15.68 MB 🚨 +156 KB 🚨
Bundle Size Analyzer Link Link

@storybook/addon-highlight

Before After Difference
Dependency count 1 1 0
Self size 12 KB 9 KB 🎉 -3 KB 🎉
Dependency size 5 KB 5 KB 🚨 +3 B 🚨
Bundle Size Analyzer Link Link

@storybook/addon-interactions

Before After Difference
Dependency count 54 56 🚨 +2 🚨
Self size 129 KB 128 KB 🎉 -2 KB 🎉
Dependency size 12.49 MB 12.74 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/addon-links

Before After Difference
Dependency count 2 4 🚨 +2 🚨
Self size 20 KB 19 KB 🎉 -1 KB 🎉
Dependency size 32 KB 284 KB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/addon-measure

Before After Difference
Dependency count 2 2 0
Self size 60 KB 32 KB 🎉 -28 KB 🎉
Dependency size 20 KB 20 KB 🚨 +3 B 🚨
Bundle Size Analyzer Link Link

@storybook/addon-outline

Before After Difference
Dependency count 2 2 0
Self size 42 KB 23 KB 🎉 -19 KB 🎉
Dependency size 32 KB 32 KB 🚨 +3 B 🚨
Bundle Size Analyzer Link Link

@storybook/addon-storysource

Before After Difference
Dependency count 5 7 🚨 +2 🚨
Self size 1.89 MB 1.89 MB 🎉 -1 KB 🎉
Dependency size 10.60 MB 10.85 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/experimental-addon-test

Before After Difference
Dependency count 58 60 🚨 +2 🚨
Self size 843 KB 831 KB 🎉 -12 KB 🎉
Dependency size 13.94 MB 14.20 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/addon-viewport

Before After Difference
Dependency count 2 2 0
Self size 30 KB 27 KB 🎉 -4 KB 🎉
Dependency size 67 KB 67 KB 🚨 +3 B 🚨
Bundle Size Analyzer Link Link

@storybook/core

Before After Difference
Dependency count 52 54 🚨 +2 🚨
Self size 19.26 MB 19.22 MB 🎉 -33 KB 🎉
Dependency size 14.26 MB 14.45 MB 🚨 +190 KB 🚨
Bundle Size Analyzer Link Link

@storybook/experimental-nextjs-vite

Before After Difference
Dependency count 186 188 🚨 +2 🚨
Self size 235 KB 232 KB 🎉 -3 KB 🎉
Dependency size 48.84 MB 48.29 MB 🎉 -553 KB 🎉
Bundle Size Analyzer Link Link

@storybook/html-vite

Before After Difference
Dependency count 15 15 0
Self size 6 KB 5 KB 🎉 -1 KB 🎉
Dependency size 1.91 MB 1.91 MB 🎉 -827 B 🎉
Bundle Size Analyzer Link Link

@storybook/html-webpack5

Before After Difference
Dependency count 251 251 0
Self size 8 KB 6 KB 🎉 -1 KB 🎉
Dependency size 32.99 MB 32.99 MB 🎉 -100 B 🎉
Bundle Size Analyzer Link Link

@storybook/nextjs

Before After Difference
Dependency count 588 589 🚨 +1 🚨
Self size 475 KB 472 KB 🎉 -3 KB 🎉
Dependency size 83.37 MB 82.62 MB 🎉 -752 KB 🎉
Bundle Size Analyzer Link Link

@storybook/preact-webpack5

Before After Difference
Dependency count 249 249 0
Self size 8 KB 6 KB 🎉 -1 KB 🎉
Dependency size 32.57 MB 32.57 MB 🎉 -571 B 🎉
Bundle Size Analyzer Link Link

@storybook/react-native-web-vite

Before After Difference
Dependency count 176 176 0
Self size 45 KB 43 KB 🎉 -2 KB 🎉
Dependency size 24.30 MB 23.50 MB 🎉 -805 KB 🎉
Bundle Size Analyzer Link Link

@storybook/react-vite

Before After Difference
Dependency count 128 128 0
Self size 15 KB 13 KB 🎉 -2 KB 🎉
Dependency size 20.48 MB 19.68 MB 🎉 -803 KB 🎉
Bundle Size Analyzer Link Link

@storybook/react-webpack5

Before After Difference
Dependency count 327 327 0
Self size 8 KB 6 KB 🎉 -2 KB 🎉
Dependency size 44.61 MB 43.81 MB 🎉 -802 KB 🎉
Bundle Size Analyzer Link Link

@storybook/server-webpack5

Before After Difference
Dependency count 257 259 🚨 +2 🚨
Self size 15 KB 14 KB 🎉 -1 KB 🎉
Dependency size 33.72 MB 33.97 MB 🚨 +251 KB 🚨
Bundle Size Analyzer Link Link

@storybook/svelte-vite

Before After Difference
Dependency count 135 134 🎉 -1 🎉
Self size 23 KB 22 KB 🎉 -1 KB 🎉
Dependency size 36.43 MB 36.38 MB 🎉 -51 KB 🎉
Bundle Size Analyzer Link Link

@storybook/svelte-webpack5

Before After Difference
Dependency count 315 314 🎉 -1 🎉
Self size 7 KB 6 KB 🎉 -1 KB 🎉
Dependency size 40.61 MB 40.56 MB 🎉 -50 KB 🎉
Bundle Size Analyzer Link Link

@storybook/sveltekit

Before After Difference
Dependency count 143 142 🎉 -1 🎉
Self size 48 KB 47 KB 🎉 -1 KB 🎉
Dependency size 39.74 MB 39.68 MB 🎉 -59 KB 🎉
Bundle Size Analyzer Link Link

@storybook/vue3-webpack5

Before After Difference
Dependency count 499 499 0
Self size 7 KB 6 KB 🎉 -1 KB 🎉
Dependency size 57.01 MB 57.01 MB 🎉 -468 B 🎉
Bundle Size Analyzer Link Link

@storybook/web-components-vite

Before After Difference
Dependency count 16 16 0
Self size 6 KB 5 KB 🎉 -1 KB 🎉
Dependency size 1.95 MB 1.94 MB 🎉 -940 B 🎉
Bundle Size Analyzer Link Link

@storybook/web-components-webpack5

Before After Difference
Dependency count 249 249 0
Self size 7 KB 5 KB 🎉 -1 KB 🎉
Dependency size 32.61 MB 32.61 MB 🎉 -215 B 🎉
Bundle Size Analyzer Link Link

@storybook/blocks

Before After Difference
Dependency count 2 4 🚨 +2 🚨
Self size 626 KB 609 KB 🎉 -17 KB 🎉
Dependency size 1.28 MB 1.53 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

storybook

Before After Difference
Dependency count 53 55 🚨 +2 🚨
Self size 23 KB 22 KB 🎉 -853 B 🎉
Dependency size 33.51 MB 33.67 MB 🚨 +158 KB 🚨
Bundle Size Analyzer Link Link

sb

Before After Difference
Dependency count 54 56 🚨 +2 🚨
Self size 1 KB 1 KB 🚨 +2 B 🚨
Dependency size 33.54 MB 33.69 MB 🚨 +157 KB 🚨
Bundle Size Analyzer Link Link

@storybook/cli

Before After Difference
Dependency count 358 387 🚨 +29 🚨
Self size 279 KB 503 KB 🚨 +224 KB 🚨
Dependency size 83.94 MB 75.59 MB 🎉 -8.34 MB 🎉
Bundle Size Analyzer Link Link

@storybook/codemod

Before After Difference
Dependency count 275 277 🚨 +2 🚨
Self size 612 KB 617 KB 🚨 +5 KB 🚨
Dependency size 65.58 MB 65.74 MB 🚨 +158 KB 🚨
Bundle Size Analyzer Link Link

create-storybook

Before After Difference
Dependency count 7 113 🚨 +106 🚨
Self size 10.21 MB 1.11 MB 🎉 -9.10 MB 🎉
Dependency size 2.24 MB 42.85 MB 🚨 +40.61 MB 🚨
Bundle Size Analyzer Link Link

@storybook/source-loader

Before After Difference
Dependency count 3 5 🚨 +2 🚨
Self size 41 KB 41 KB 🎉 -12 B 🎉
Dependency size 10.54 MB 10.79 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/test

Before After Difference
Dependency count 51 53 🚨 +2 🚨
Self size 1.82 MB 1.82 MB 🚨 +12 B 🚨
Dependency size 7.85 MB 8.10 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/preset-react-webpack

Before After Difference
Dependency count 182 182 0
Self size 24 KB 24 KB 🎉 -2 B 🎉
Dependency size 31.73 MB 30.92 MB 🎉 -802 KB 🎉
Bundle Size Analyzer Link Link

@storybook/preset-server-webpack

Before After Difference
Dependency count 16 18 🚨 +2 🚨
Self size 10 KB 10 KB 🎉 -2 B 🎉
Dependency size 1.23 MB 1.48 MB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/react

Before After Difference
Dependency count 6 6 0
Self size 1.73 MB 933 KB 🎉 -802 KB 🎉
Dependency size 24 KB 24 KB 🚨 +26 B 🚨
Bundle Size Analyzer Link Link

@storybook/server

Before After Difference
Dependency count 7 9 🚨 +2 🚨
Self size 13 KB 13 KB 🚨 +34 B 🚨
Dependency size 722 KB 974 KB 🚨 +252 KB 🚨
Bundle Size Analyzer Link Link

@storybook/svelte

Before After Difference
Dependency count 107 106 🎉 -1 🎉
Self size 96 KB 96 KB 🚨 +292 B 🚨
Dependency size 10.64 MB 10.59 MB 🎉 -50 KB 🎉
Bundle Size Analyzer Link Link

@valentinpalkovic valentinpalkovic changed the title Docs: Support async docs.source.transform Source: Support async parameters.docs.source.transform Jan 31, 2025
@valentinpalkovic valentinpalkovic marked this pull request as ready for review January 31, 2025 10:22
Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

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

4 file(s) reviewed, 4 comment(s)
Edit PR Review Bot Settings | Greptile

Copy link
Contributor

@JReinhold JReinhold left a comment

Choose a reason for hiding this comment

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

A few comments.
I also think it deserves a migration note, describing how you can implement the current formatter as an async transfomer.

Probably also needs @shilman's blessing on deprecating docs.source.format in favor of asking users to implement their own if they want to, probably with prettier.

The rationale is that the current format feature is half-baked because it only supports a hard-coded limited set of languages, and it requires a hefty prettier bundled in.

const sourceParameters = (storyContext.parameters.docs?.source || {}) as SourceParameters;
const parameters = storyContext.parameters ?? {};
const { __isArgsStory: isArgsStory } = parameters;
const [transformedCode, setTransformedCode] = useState('Loading...');
Copy link
Contributor

Choose a reason for hiding this comment

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

  1. Maybe 'Transforming...' instead of 'Loading...'?
  2. the default could also just be code if we detect that there is no transformer, and 'Transforming...' if there is?
  3. The default could also just always be code, to be replaced by the transformed code afterwards.

Copy link
Contributor Author

@valentinpalkovic valentinpalkovic Jan 31, 2025

Choose a reason for hiding this comment

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

the default could also just be code if we detect that there is no transformer, and 'Transforming...' if there is?

It is a bit of a spaghetti code, but at the bottom of the hook, transformedCode is not used if code is defined. I don't prefer to set the default to code because then you might have a flickering between two codes, and you might not understand why it was changing. Transforming... indicates that the transformation is still in progress and you should wait to interpret the code. transform can not just be used to format code, but also to display something completely different (I think we use a very custom transformer for Angular for example).


Type: `boolean | 'dedent' | BuiltInParserName`

Default: `parameters.docs.source.format` or `true`

Deprecated: Will be removed in Storybook 9. Please use `docs.source.transform` instead and use your own formatter
Copy link
Contributor

Choose a reason for hiding this comment

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

I think an example of how to do this with prettier here would come a long way.

Copy link
Member

Choose a reason for hiding this comment

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

Agree

@valentinpalkovic
Copy link
Contributor Author

Good catches! I'll take care of it.

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

Successfully merging this pull request may close these issues.

4 participants