Merge pull request #35665 from storybookjs/julien/vue_docgen_rendzerer

Vue: Move vue-component-meta in vue renderer and implement docgen payload builder

Author: huang-julien

code/core/src/common/index.ts

@@ -2,6 +2,7 @@ import versions from './versions.ts';
 
 /// <reference types="@types/compression" />
 
+export { jsTsSourceExtensions } from '../shared/constants/extensions.ts';
 export * from './presets.ts';
 export * from './utils/cache.ts';
 export * from './utils/cli.ts';
@@ -24,6 +25,7 @@ export * from './utils/load-main-config.ts';
 export * from './utils/load-manager-or-addons-file.ts';
 export * from './utils/load-preview-or-config-file.ts';
 export * from './utils/log-config.ts';
+export * from './utils/module-resolver.ts';
 export * from './utils/normalize-stories.ts';
 export * from './utils/paths.ts';
 export * from './utils/read-dependency-manifest.ts';
@@ -40,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/interpret-files.ts

@@ -1,9 +1,8 @@
 import { existsSync } from 'node:fs';
 import { extname } from 'node:path';
 
-import { ResolverFactory } from 'oxc-resolver';
-
 import { storybookConfigExtensions } from '../../shared/constants/extensions.ts';
+import { createModuleResolver } from './module-resolver.ts';
 
 const typescriptFallbackExtensions: Record<string, string[]> = {
   '.js': ['.ts', '.tsx'],
@@ -20,7 +19,7 @@ export function getInterpretedFile(pathToFile: string) {
     .find((candidate) => existsSync(candidate));
 }
 
-const importResolver = new ResolverFactory({
+const importResolver = createModuleResolver({
   extensions: [...supportedExtensions],
   mainFields: ['module', 'main'],
 });
@@ -61,9 +60,5 @@ export function resolveImport(id: string, options: ResolveImportOptions): string
 }
 
 function resolveSync(id: string, basedir: string): string {
-  const result = importResolver.sync(basedir, id);
-  if (result.path) {
-    return result.path;
-  }
-  throw new Error(result.error ?? `Cannot resolve module '${id}' from '${basedir}'`);
+  return importResolver.resolveSync(basedir, id);
 }

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/common/utils/module-resolver.ts

@@ -0,0 +1,42 @@
+import { ResolverFactory } from 'oxc-resolver';
+
+/**
+ * Module resolution options, declared locally so consumers don't depend on the underlying resolver
+ * package.
+ */
+export interface ModuleResolverOptions {
+  extensions?: string[];
+  mainFields?: string[];
+  conditionNames?: string[];
+  /** Honor `paths`/`baseUrl` from a tsconfig. `'auto'` walks up from the resolution origin. */
+  tsconfig?: 'auto' | { configFile: string };
+}
+
+export interface ModuleResolver {
+  /** Resolves `specifier` as if imported from `fromFile`. Throws when unresolvable. */
+  resolveFileSync(fromFile: string, specifier: string): string;
+  /** Resolves `specifier` as if imported from a file in `fromDirectory`. Throws when unresolvable. */
+  resolveSync(fromDirectory: string, specifier: string): string;
+}
+
+export function createModuleResolver(options: ModuleResolverOptions = {}): ModuleResolver {
+  const factory = new ResolverFactory(options);
+
+  const unwrap = (
+    result: { path?: string | null; error?: string | null },
+    specifier: string,
+    from: string
+  ) => {
+    if (result.path) {
+      return result.path;
+    }
+    throw new Error(result.error ?? `Cannot resolve module '${specifier}' from '${from}'`);
+  };
+
+  return {
+    resolveFileSync: (fromFile, specifier) =>
+      unwrap(factory.resolveFileSync(fromFile, specifier), specifier, fromFile),
+    resolveSync: (fromDirectory, specifier) =>
+      unwrap(factory.sync(fromDirectory, specifier), specifier, fromDirectory),
+  };
+}

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

@@ -51,20 +51,25 @@
   "dependencies": {
     "@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"
+    "magic-string": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.1",
     "typescript": "^6.0.3",
-    "vite": "^7.0.4"
+    "vite": "^7.0.4",
+    "vue-component-meta": "^3.3.9",
+    "vue-docgen-api": "^4.75.1"
   },
   "peerDependencies": {
     "storybook": "workspace:^",
+    "typescript": ">= 4.9.x",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
   },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },

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

@@ -0,0 +1,49 @@
+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;
+  }
+
+  if (docgen === undefined || docgen === true) {
+    return { plugin: 'vue-docgen-api' };
+  }
+
+  if (typeof docgen === 'string') {
+    return { plugin: docgen };
+  }
+
+  return docgen;
+}

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({});
+  });
+});