Vue: Fix `vue-component-meta` docgen HMR not working #29518

IonianPlayboy · 2024-11-03T00:45:37Z

What I did

Currently, the vue-component-meta plugin is only running when Storybook is initially launched, but it never updates afterwards. The only way to get the updated values inside Storybook is to stop the dev server and relaunch it everytime there is a change, which is a far from ideal DX experience.

This PR proposes two steps (each in a separate commit) to improve the current experience :

Update the generated meta whenever the component is changed. This allows the users at the very least to refresh the Storybook page inside the browser to get the updated meta inside theirs stories, without having to restart the dev server.
Once the component meta has been updated, trigger a full reload. With this change, there is no actions needed from the user to see the updated meta inside theirs stories. I am not very familiar with Vite HMR API or the way Storybook integrates it in its own builder, so maybe there is a more efficient to achieve the same result here without a full reload.

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!

Run a sandbox for the Vue 3 Vite template, e.g. yarn task --task sandbox --start-from auto --template vue3-vite/default-ts
Update the generated .storybook/main.ts to use the vue-component-meta plugin for docgen:

 framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: {
        plugin: 'vue-component-meta',
        tsconfig: 'tsconfig.app.json',
      },
    },
  },

Open Storybook in your browser
Access the Button story
Update the Button.vue component to change the generated meta, for example with a new prop:

  /**
   * add border to the button
   */
  withBorder?: boolean,

Confirm that the Button story has been updated correctly, for example with the added withBorder prop:

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	78.2 MB	78.2 MB	0 B	1.16	0%
initSize	143 MB	143 MB	2.83 kB	1.18	0%
diffSize	65.1 MB	65.1 MB	2.83 kB	1.16	0%
buildSize	6.88 MB	6.88 MB	0 B	1.12	0%
buildSbAddonsSize	1.51 MB	1.51 MB	0 B	-	0%
buildSbCommonSize	195 kB	195 kB	0 B	-	0%
buildSbManagerSize	1.9 MB	1.9 MB	0 B	1.11	0%
buildSbPreviewSize	271 kB	271 kB	0 B	-	0%
buildStaticSize	0 B	0 B	0 B	-	-
buildPrebuildSize	3.88 MB	3.88 MB	0 B	1.11	0%
buildPreviewSize	3 MB	3 MB	0 B	1.11	0%
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.5s	6.7s	164ms	-0.92	2.4%
generateTime	19.5s	19.8s	333ms	-0.65	1.7%
initTime	13.5s	15.9s	2.3s	0.28	14.9%
buildTime	8.1s	8.8s	660ms	-0.22	7.5%
testBuildTime	0ms	0ms	0ms	-	-
devPreviewResponsive	5.5s	5.1s	-314ms	-1.06	-6.1%
devManagerResponsive	3.5s	3.3s	-150ms	-0.89	-4.4%
devManagerHeaderVisible	473ms	553ms	80ms	-0.52	14.5%
devManagerIndexVisible	500ms	607ms	107ms	-0.56	17.6%
devStoryVisibleUncached	602ms	894ms	292ms	-0.45	32.7%
devStoryVisible	499ms	580ms	81ms	-0.74	14%
devAutodocsVisible	467ms	505ms	38ms	-0.39	7.5%
devMDXVisible	450ms	488ms	38ms	-0.55	7.8%
buildManagerHeaderVisible	631ms	505ms	-126ms	-0.85	-25%
buildManagerIndexVisible	648ms	516ms	-132ms	-0.85	-25.6%
buildStoryVisible	630ms	509ms	-121ms	-0.8	-23.8%
buildAutodocsVisible	477ms	425ms	-52ms	-0.72	-12.2%
buildMDXVisible	478ms	423ms	-55ms	-0.66	-13%

Greptile Summary

Enhanced HMR functionality for Vue component metadata in Storybook by adding support for dynamic updates without requiring server restarts.

Added handleHotUpdate hook in code/frameworks/vue3-vite/src/plugins/vue-component-meta.ts to update component metadata on file changes
Implemented module invalidation using Vite's HMR API to ensure proper cache clearing
Added full page reload trigger via WebSocket to refresh component documentation
Fixed issue [Bug]: vue-component-meta docgen HMR not working #27514 where vue-component-meta docgen changes weren't reflected without server restart

greptile-apps

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

greptile-apps · 2024-11-03T00:46:07Z

code/frameworks/vue3-vite/src/plugins/vue-component-meta.ts

+    async handleHotUpdate({ file, read, server, modules, timestamp }) {
+      const content = await read();
+      checker.updateFile(file, content);
+      // Invalidate modules manually
+      const invalidatedModules = new Set<ModuleNode>();
+
+      for (const mod of modules) {
+        server.moduleGraph.invalidateModule(mod, invalidatedModules, timestamp, true);
+      }
+
+      server.ws.send({ type: 'full-reload' });
+      return [];
+    },


style: Consider using more granular HMR updates instead of full page reload. A full reload works but may impact development experience for large applications.

kasperpeulen · 2024-11-11T14:14:14Z

@larsrickert What do you think about this?

IonianPlayboy · 2024-11-23T23:59:14Z

Hello, is there anything I can do to help the review process ? 😊

kasperpeulen · 2024-11-25T08:31:02Z

I'm mostly wondering if this part was intentional @larsrickert @chakAs3

Currently, the vue-component-meta plugin is only running when Storybook is initially launched, but it never updates afterwards.

IonianPlayboy · 2024-11-25T10:17:00Z

I can't be 100% sure about this, but I think it is interesting to note that this behaviour is not consistent with vue-docgen, the other (older) docgen plugin available for the vue3-vite builder.

This is why we are still using vue-docgen at my company instead of the newer vue-component-meta plugin, but Storybook mentions in its documentation that the plan is to make vue-component-meta the default in a future version.

If that happens without changing the HMR behaviour, that would be a breaking change for Vue users in my opinion.

larsrickert · 2024-11-25T10:32:07Z

I'm mostly wondering if this part was intentional @larsrickert @chakAs3

Currently, the vue-component-meta plugin is only running when Storybook is initially launched, but it never updates afterwards.

Hey, not as far as I remember. My thought was that HMR will come out of the box and we don‘t have to explicitly implement it. So I’d consider this a bug.

IonianPlayboy · 2024-11-25T11:50:06Z

My thought was that HMR will come out of the box and we don‘t have to explicitly implement it

For the record, I looked into nuxtlabs/nuxt-component-meta's source code while working on this PR to see if they had the same problem or not, and that's how I found out about checker.updateFile :

https://github.com/nuxtlabs/nuxt-component-meta/blob/a6efba49ead68e63d38047f8a9b2a8aefd752d06/src/parser.ts#L178-L179

They also have a handleHotUpdate method in their Vite plugin to refresh the component meta for HMR :

https://github.com/nuxtlabs/nuxt-component-meta/blob/a6efba49ead68e63d38047f8a9b2a8aefd752d06/src/unplugin.ts#L12-L32

The PR implementing these changes also explicitely mentions that it was done to support HMR : nuxtlabs/nuxt-component-meta#43

kasperpeulen

LGTM!

nx-cloud · 2024-11-26T08:38:12Z

☁️ Nx Cloud Report

CI is running/has finished running commands for commit b9ac9dd. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

✅ Successfully ran 1 target

nx run-many -t build --parallel=3

Sent with 💌 from NxCloud.

chakAs3 · 2024-11-29T18:33:39Z

Hi @kasperpeulen, @larsrickert, This is expected behavior and has always been the case—it’s not related to vue-component-meta. It’s due to how Storybook uses the file transformer plugin in the server preset to generate component metadata, which runs only once. The same applies to React; the component docgen table has never supported HMR. but you don't have to restart the dev server just reload the page

So @IonianPlayboy , I agree the DX experience isn’t great, but this limitation applies to all Storybook renderers, including React, I believe.

IonianPlayboy · 2024-11-29T20:49:09Z

@chakAs3 I understand your point and if that's the intended behavior for all frameworks, then there's no reason to do anything different for Vue, and the changes in b9ac9dd can be reverted.

However, there is something significant I want to point out:

The same applies to React; the component docgen table has never supported HMR. but you don't have to restart the dev server just reload the page

This was NOT the case with the vue-component-meta docgen plugin before this PR. You always had to restart the server to see the updated values, full stop. This is why I feel it's still very important to keep the changes in 4ae12fe, because otherwise the DX suffers a lot and is not on par with the other Storybook integrations.

Currently, Vue users have two options for their docgen plugin:

The old vue-docgen-api, which generates less precise docs (it limits a lot how you can type your props for example)
The newer vue-component-meta, but you have to restart the dev server everytime you update your types

It is in my opinion one of the main pain points of working with Storybook + Vue, so I hope we can still improve it a bit here.

(Also, as I mentioned in #29518 (comment), this is not consistent with the behavior of the vue-docgen-api, and Storybook is going to deprecate it in the future in favor of the vue-component-meta plugin. If this issue is not fixed at that point, that would be a breaking change in my eyes.)

greptile-apps bot reviewed Nov 3, 2024

View reviewed changes

jonniebigodes assigned kasperpeulen Nov 4, 2024

jonniebigodes added vue3 bug ci:normal labels Nov 4, 2024

IonianPlayboy force-pushed the fix-vue3-vite-hmr-docgen branch from fc67014 to 9b9889d Compare November 4, 2024 17:52

Nathanaël Labreuil added 2 commits November 5, 2024 12:33

feat: update component meta on file change

4ae12fe

feat: invalidate modules and trigger full reload on file change

b9ac9dd

IonianPlayboy force-pushed the fix-vue3-vite-hmr-docgen branch from 9b9889d to b9ac9dd Compare November 5, 2024 11:33

kasperpeulen assigned larsrickert Nov 11, 2024

kasperpeulen approved these changes Nov 26, 2024

View reviewed changes

kasperpeulen changed the title ~~Vue: fix vue-component-meta docgen HMR not working~~ Vue: Fix vue-component-meta docgen HMR not working Nov 26, 2024

kasperpeulen enabled auto-merge November 26, 2024 16:05

kasperpeulen merged commit 965b4c1 into storybookjs:next Nov 26, 2024
54 of 55 checks passed

IonianPlayboy deleted the fix-vue3-vite-hmr-docgen branch November 26, 2024 16:16

github-actions bot mentioned this pull request Nov 27, 2024

Release: Prerelease 8.5.0-alpha.11 #29700

Merged

12 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Vue: Fix `vue-component-meta` docgen HMR not working #29518

Vue: Fix `vue-component-meta` docgen HMR not working #29518

IonianPlayboy commented Nov 3, 2024 •

edited by storybook-pr-benchmarking bot

Loading

greptile-apps bot left a comment

greptile-apps bot Nov 3, 2024

kasperpeulen commented Nov 11, 2024

IonianPlayboy commented Nov 23, 2024

kasperpeulen commented Nov 25, 2024

IonianPlayboy commented Nov 25, 2024

larsrickert commented Nov 25, 2024

IonianPlayboy commented Nov 25, 2024

kasperpeulen left a comment

nx-cloud bot commented Nov 26, 2024

chakAs3 commented Nov 29, 2024 •

edited

Loading

IonianPlayboy commented Nov 29, 2024 •

edited

Loading

Vue: Fix vue-component-meta docgen HMR not working #29518

Vue: Fix vue-component-meta docgen HMR not working #29518

Conversation

IonianPlayboy commented Nov 3, 2024 • edited by storybook-pr-benchmarking bot Loading

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

greptile-apps bot left a comment

Choose a reason for hiding this comment

greptile-apps bot Nov 3, 2024

Choose a reason for hiding this comment

kasperpeulen commented Nov 11, 2024

IonianPlayboy commented Nov 23, 2024

kasperpeulen commented Nov 25, 2024

IonianPlayboy commented Nov 25, 2024

larsrickert commented Nov 25, 2024

IonianPlayboy commented Nov 25, 2024

kasperpeulen left a comment

Choose a reason for hiding this comment

nx-cloud bot commented Nov 26, 2024

☁️ Nx Cloud Report

chakAs3 commented Nov 29, 2024 • edited Loading

IonianPlayboy commented Nov 29, 2024 • edited Loading

Vue: Fix `vue-component-meta` docgen HMR not working #29518

Vue: Fix `vue-component-meta` docgen HMR not working #29518

IonianPlayboy commented Nov 3, 2024 •

edited by storybook-pr-benchmarking bot

Loading

chakAs3 commented Nov 29, 2024 •

edited

Loading

IonianPlayboy commented Nov 29, 2024 •

edited

Loading