Vue: Run docgen through component-meta project manager

code/core/src/common/index.ts

@@ -42,6 +42,7 @@ export * from './utils/formatter.ts';
 export * from './utils/get-story-id.ts';
 export * from './utils/component-id.ts';
 export * from './utils/select-component-entry.ts';
+export * from './utils/lazy-docgen-middleware.ts';
 export * from './utils/posix.ts';
 export * from './utils/sync-main-preview-addons.ts';
 export * from './utils/setup-addon-in-config.ts';

code/core/src/common/utils/lazy-docgen-middleware.ts

@@ -0,0 +1,50 @@
+import type {
+  DocgenMiddleware,
+  DocgenPayload,
+  DocgenProvider,
+  DocgenProviderInput,
+} from '../../shared/open-service/services/docgen/types.ts';
+import { STORY_FILE_TEST_REGEXP, getStoryImportPathFromEntry } from './select-component-entry.ts';
+
+export interface LazyDocgenMiddlewareOptions<TManager> {
+  /**
+   * Builds the renderer's extraction manager.
+   * Called once, lazily, on the first eligible request and memoized for the worker's lifetime.
+   * Return `undefined` to permanently pass through to the rest of the chain.
+   */
+  createManager: () => Promise<TManager | undefined>;
+  /**
+   * Extracts one payload
+   * Returns `undefined` to delegate the request downstream
+   */
+  extract: (manager: TManager, input: DocgenProviderInput) => Promise<DocgenPayload | undefined>;
+}
+
+export function createLazyDocgenMiddleware<TManager>({
+  createManager,
+  extract,
+}: LazyDocgenMiddlewareOptions<TManager>): DocgenMiddleware {
+  let managerPromise: Promise<TManager | undefined> | undefined;
+  const getManager = () => (managerPromise ??= createManager());
+
+  return (nextDocgen: DocgenProvider): DocgenProvider =>
+    async (input) => {
+      const storyImportPath = getStoryImportPathFromEntry(input.entry);
+      if (!storyImportPath || !STORY_FILE_TEST_REGEXP.test(storyImportPath)) {
+        return nextDocgen(input);
+      }
+
+      const manager = await getManager();
+      if (!manager) {
+        return nextDocgen(input);
+      }
+
+      const ours = await extract(manager, input);
+      if (!ours) {
+        return nextDocgen(input);
+      }
+
+      const downstream = await nextDocgen(input);
+      return { ...downstream, ...ours };
+    };
+}

code/core/src/types/modules/core-common.ts

@@ -459,7 +459,11 @@ export interface ComponentsManifest {
   v: number;
   components: Record<string, ComponentManifest>;
   meta?: {
-    docgen: 'react-docgen' | 'react-docgen-typescript' | 'react-component-meta';
+    docgen:
+      | 'react-docgen'
+      | 'react-docgen-typescript'
+      | 'react-component-meta'
+      | 'vue-component-meta';
     durationMs: number;
   };
 }

code/frameworks/vue3-vite/package.json

@@ -52,7 +52,6 @@
     "@storybook/builder-vite": "workspace:*",
     "@storybook/vue3": "workspace:*",
     "magic-string": "^1.1.0",
-    "typescript": "^5.9.3",
     "vue-component-meta": "^3.3.9",
     "vue-docgen-api": "^4.75.1"
   },

code/frameworks/vue3-vite/src/docgen/errors.ts

@@ -0,0 +1,14 @@
+import { Category, StorybookError } from 'storybook/internal/server-errors';
+
+export class Vue3ViteDocgenManifestError extends StorybookError {
+  constructor() {
+    super({
+      name: 'Vue3ViteDocgenManifestError',
+      category: Category.FRAMEWORK_VUE3_VITE,
+      code: 1,
+      message:
+        "The Vue docgen manifest currently requires `docgen: 'vue-component-meta'` in `framework.options`.\n" +
+        'Update the Vue framework configuration or disable `features.componentsManifest`.',
+    });
+  }
+}

code/frameworks/vue3-vite/src/docgen/options.ts

@@ -1,7 +1,37 @@
+import type { Options, StorybookConfigRaw } from 'storybook/internal/types';
+
 import type { FrameworkOptions, VueDocgenPlugin } from '../types.ts';
 
+export const VUE_COMPONENT_META = 'vue-component-meta' satisfies VueDocgenPlugin;
+
 export type ResolvedDocgenOptions = false | { plugin: VueDocgenPlugin; tsconfig?: string };
 
+export interface DocgenContext {
+  docgen: ResolvedDocgenOptions;
+  features: StorybookConfigRaw['features'];
+  /**
+   * Only true if the docgen server is active and the `vue-component-meta` plugin is selected.
+   */
+  docgenServerActive: boolean;
+}
+
+export async function resolveDocgenContext(options: Options): Promise<DocgenContext> {
+  const [frameworkOptions, features] = await Promise.all([
+    options.presets.apply<FrameworkOptions | null>('frameworkOptions'),
+    options.presets.apply('features', {}),
+  ]);
+  const docgen = resolveDocgenOptions(frameworkOptions?.docgen);
+
+  return {
+    docgen,
+    features,
+    docgenServerActive:
+      features?.experimentalDocgenServer === true &&
+      docgen !== false &&
+      docgen.plugin === VUE_COMPONENT_META,
+  };
+}
+
 export function resolveDocgenOptions(docgen?: FrameworkOptions['docgen']): ResolvedDocgenOptions {
   if (docgen === false) {
     return false;

code/frameworks/vue3-vite/src/docgen/preset.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+
+import type { DocgenProviderDescriptor, Options } from 'storybook/internal/types';
+
+import type { FrameworkOptions } from '../types.ts';
+import { experimental_docgenProvider, experimental_manifests } from './preset.ts';
+
+const optionsWith = (docgen?: FrameworkOptions['docgen'], features: Record<string, boolean> = {}) =>
+  ({
+    presets: {
+      apply: async (key: string) => {
+        if (key === 'frameworkOptions') {
+          return { docgen };
+        }
+        return key === 'features' ? features : {};
+      },
+    },
+  }) as unknown as Options;
+
+const existing: DocgenProviderDescriptor[] = [{ moduleSpecifier: '/addon/docgen-worker.js' }];
+const docgenServerOn = { experimentalDocgenServer: true };
+const componentsManifestOn = { ...docgenServerOn, componentsManifest: true };
+
+describe('experimental_docgenProvider', () => {
+  it('appends a descriptor pointing at the renderer worker module', async () => {
+    const descriptors = await experimental_docgenProvider(
+      existing,
+      optionsWith('vue-component-meta', docgenServerOn)
+    );
+
+    expect(descriptors).toHaveLength(2);
+    // Appended, so addon providers stack on top of ours rather than replacing it.
+    expect(descriptors[0]).toBe(existing[0]);
+    expect(descriptors[1].moduleSpecifier).toMatch(/docgen-worker\.js$/);
+  });
+
+  // The worker extracts with vue-component-meta only. Registering for vue-docgen-api would
+  // silently swap the engine the project asked for; `docgen: false` opted out of extraction
+  // altogether and must stay opted out.
+  it.each(['vue-docgen-api' as const, undefined, false as const])(
+    'registers nothing for docgen: %s',
+    async (docgen) => {
+      await expect(
+        experimental_docgenProvider(existing, optionsWith(docgen, docgenServerOn))
+      ).resolves.toEqual(existing);
+    }
+  );
+});
+
+describe('experimental_manifests', () => {
+  const manifests = (docgen?: FrameworkOptions['docgen'], features?: Record<string, boolean>) =>
+    experimental_manifests({}, optionsWith(docgen, features) as never);
+
+  // Core asserts `components.meta.docgen` is present whenever the feature is on, so omitting it
+  // fails a Vue `storybook build` outright rather than degrading the debugger.
+  it('declares the engine so core can label the components debugger', async () => {
+    await expect(manifests('vue-component-meta', componentsManifestOn)).resolves.toEqual({
+      components: { v: 0, components: {}, meta: { docgen: 'vue-component-meta', durationMs: 0 } },
+    });
+  });
+
+  it.each(['vue-docgen-api' as const, undefined, false as const])(
+    'rejects the components manifest for docgen: %s',
+    async (docgen) => {
+      await expect(manifests(docgen, componentsManifestOn)).rejects.toThrow(
+        "The Vue docgen manifest currently requires `docgen: 'vue-component-meta'` in `framework.options`."
+      );
+    }
+  );
+
+  // The manifest is populated from docgen-service payloads. When another engine (or none) runs,
+  // there are no payloads, so claiming an engine here would report "0 components" against it.
+  it.each(['vue-docgen-api' as const, undefined, false as const])(
+    'contributes nothing for docgen: %s',
+    async (docgen) => {
+      await expect(manifests(docgen, docgenServerOn)).resolves.toEqual({});
+    }
+  );
+
+  // Vue has no legacy component manifest, so with the feature off there is nothing to contribute.
+  it('contributes nothing when the docgen service is off', async () => {
+    await expect(manifests('vue-component-meta')).resolves.toEqual({});
+  });
+});

code/frameworks/vue3-vite/src/docgen/preset.ts

@@ -0,0 +1,64 @@
+import { fileURLToPath } from 'node:url';
+
+import type {
+  DocgenProviderDescriptor,
+  IndexEntry,
+  Options,
+  PresetPropertyFn,
+  StorybookConfigRaw,
+} from 'storybook/internal/types';
+
+import { Vue3ViteDocgenManifestError } from './errors.ts';
+import { VUE_COMPONENT_META, resolveDocgenContext } from './options.ts';
+
+/**
+ * Vue docgen provider.
+ *
+ * Contributes a {@link DocgenProviderDescriptor} pointing at `@storybook/vue3/internal/docgen-worker`
+ */
+export const experimental_docgenProvider = async (
+  existing: DocgenProviderDescriptor[] = [],
+  options: Options
+): Promise<DocgenProviderDescriptor[]> => {
+  const { docgenServerActive } = await resolveDocgenContext(options);
+
+  if (!docgenServerActive) {
+    return existing;
+  }
+
+  return [
+    ...existing,
+    {
+      moduleSpecifier: fileURLToPath(import.meta.resolve('@storybook/vue3/internal/docgen-worker')),
+    },
+  ];
+};
+
+export const experimental_manifests: PresetPropertyFn<
+  'experimental_manifests',
+  StorybookConfigRaw,
+  { manifestEntries: IndexEntry[]; watch: boolean }
+> = async (existingManifests = {}, options) => {
+  const { features, docgenServerActive } = await resolveDocgenContext(options);
+
+  if (
+    features?.experimentalDocgenServer === true &&
+    features.componentsManifest === true &&
+    !docgenServerActive
+  ) {
+    throw new Vue3ViteDocgenManifestError();
+  }
+
+  if (!docgenServerActive) {
+    return existingManifests;
+  }
+
+  return {
+    ...existingManifests,
+    components: {
+      v: 0,
+      components: {},
+      meta: { docgen: VUE_COMPONENT_META, durationMs: 0 },
+    },
+  };
+};

code/frameworks/vue3-vite/src/preset.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { Options } from 'storybook/internal/types';
+
+import { vueComponentMeta } from './plugins/vue-component-meta.ts';
+import { vueDocgen } from './plugins/vue-docgen.ts';
+import { templateCompilation } from './plugins/vue-template.ts';
+import type { FrameworkOptions } from './types.ts';
+
+// The real plugin factories build a vue-component-meta checker / vue-docgen-api parser, which is
+// far too heavy for a preset test. Identify them by name instead.
+vi.mock('./plugins/vue-template.ts', { spy: true });
+vi.mock('./plugins/vue-component-meta.ts', { spy: true });
+vi.mock('./plugins/vue-docgen.ts', { spy: true });
+
+beforeEach(() => {
+  vi.mocked(templateCompilation).mockResolvedValue({ name: 'template' });
+  vi.mocked(vueComponentMeta).mockResolvedValue({ name: 'vue-component-meta' });
+  vi.mocked(vueDocgen).mockResolvedValue({ name: 'vue-docgen-api' });
+});
+
+const optionsWith = (docgen: FrameworkOptions['docgen'], features: Record<string, boolean> = {}) =>
+  ({
+    presets: {
+      apply: async (key: string) => {
+        if (key === 'frameworkOptions') {
+          return { docgen };
+        }
+        return key === 'features' ? features : {};
+      },
+    },
+  }) as unknown as Options;
+
+const pluginNames = async (
+  docgen: FrameworkOptions['docgen'],
+  features?: Record<string, boolean>
+) => {
+  const { viteFinal } = await import('./preset.ts');
+  const config = await viteFinal!({}, optionsWith(docgen, features));
+  return (config.plugins ?? []).map((plugin) => (plugin as { name: string }).name);
+};
+
+describe('viteFinal', () => {
+  it.each([
+    ['vue-component-meta' as const, 'vue-component-meta'],
+    [undefined, 'vue-docgen-api'],
+  ])('adds the %s docgen plugin when the docgen service is off', async (docgen, expected) => {
+    expect(await pluginNames(docgen)).toEqual(['template', expected]);
+  });
+
+  // The service extracts the same metadata, so leaving the plugin on would compile every component
+  // twice and put a `__docgenInfo` in the preview bundle that nothing reads.
+  it('omits the vue-component-meta plugin when the docgen service is on', async () => {
+    expect(await pluginNames('vue-component-meta', { experimentalDocgenServer: true })).toEqual([
+      'template',
+    ]);
+  });
+
+  // vue-docgen-api has no worker-side extractor, so the feature flag must not strip its plugin —
+  // that would leave these projects with no docgen at all.
+  it.each(['vue-docgen-api' as const, undefined])(
+    'keeps the docgen plugin for docgen: %s even when the docgen service is on',
+    async (docgen) => {
+      expect(await pluginNames(docgen, { experimentalDocgenServer: true })).toEqual([
+        'template',
+        'vue-docgen-api',
+      ]);
+    }
+  );
+
+  it('keeps template compilation when docgen is disabled', async () => {
+    expect(await pluginNames(false)).toEqual(['template']);
+  });
+});

code/frameworks/vue3-vite/src/preset.ts

@@ -2,11 +2,13 @@ import type { PresetProperty } from 'storybook/internal/types';
 
 import type { Plugin } from 'vite';
 
-import { resolveDocgenOptions } from './docgen/options.ts';
+import { VUE_COMPONENT_META, resolveDocgenContext } from './docgen/options.ts';
 import { type VueDocgenEngine, vueComponentMeta } from './plugins/vue-component-meta.ts';
 import { vueDocgen } from './plugins/vue-docgen.ts';
 import { templateCompilation } from './plugins/vue-template.ts';
-import type { FrameworkOptions, StorybookConfig } from './types.ts';
+import type { StorybookConfig } from './types.ts';
+
+export { experimental_docgenProvider, experimental_manifests } from './docgen/preset.ts';
 
 export const core: PresetProperty<'core'> = {
   builder: import.meta.resolve('@storybook/builder-vite'),
@@ -16,15 +18,11 @@ export const core: PresetProperty<'core'> = {
 export const viteFinal: StorybookConfig['viteFinal'] = async (config, options) => {
   const plugins: Plugin[] = [await templateCompilation()];
 
-  const framework = await options.presets.apply('framework');
-  const frameworkOptions: FrameworkOptions =
-    typeof framework === 'string' ? {} : (framework.options ?? {});
-
-  const docgen = resolveDocgenOptions(frameworkOptions.docgen);
+  const { docgen, docgenServerActive } = await resolveDocgenContext(options);
 
   // add docgen plugin depending on framework option
-  if (docgen !== false) {
-    if (docgen.plugin === 'vue-component-meta') {
+  if (docgen !== false && !docgenServerActive) {
+    if (docgen.plugin === VUE_COMPONENT_META) {
       const engine: VueDocgenEngine = await options.presets.apply('experimental_vueDocgenEngine');
       plugins.push(await vueComponentMeta(engine, docgen.tsconfig));
     } else {