@storybook-astro/framework 1.2.0 → 1.3.0-canary.2

package/src/productionRenderRuntime.ts

@@ -0,0 +1,187 @@
+import { resolve } from 'node:path';
+import { createAstroRenderHandler, type HandlerProps } from './astroRenderHandler.ts';
+import type { Integration } from './integrations/index.ts';
+import type { SanitizationOptions } from './lib/sanitization.ts';
+import {
+  createClientModuleResolver,
+  createProductionAstroContainer,
+  createStorySsrViteServer,
+  loadRulesConfigModule
+} from './storySsrVite.ts';
+
+type LoadedStoryModule = Record<string, unknown>;
+
+export type ProductionRenderRuntime = {
+  loadModule: (moduleId: string) => Promise<LoadedStoryModule>;
+  renderAstroStory: (data: HandlerProps) => Promise<string>;
+  close: () => Promise<void>;
+};
+
+export type ProductionStoryEntry = {
+  id: string;
+  importPath: string;
+  componentPath: string;
+  exportName: string;
+  title?: string;
+  name?: string;
+};
+
+type ProductionRenderRuntimeOptions = {
+  integrations: Integration[];
+  sanitization?: SanitizationOptions;
+  storyRulesConfigFilePath?: string;
+  staticModuleMap: Record<string, string>;
+  trackedSpecifiers: Set<string>;
+  resolveFrom: string;
+  resolveComponentId?: (id: string) => string;
+};
+
+/** Creates the shared SSR runtime used by both build-time prerendering and the standalone render server. */
+export async function createProductionRenderRuntime(
+  options: ProductionRenderRuntimeOptions
+): Promise<ProductionRenderRuntime> {
+  const viteServer = await createStorySsrViteServer({
+    integrations: options.integrations,
+    trackedSpecifiers: options.trackedSpecifiers,
+    resolveFrom: options.resolveFrom
+  });
+
+  try {
+    const rulesConfigModule = await loadRulesConfigModule(
+      viteServer,
+      options.storyRulesConfigFilePath
+    );
+    const resolveClientModule = createClientModuleResolver(
+      options.integrations,
+      options.staticModuleMap
+    );
+    const astroContainer = await createProductionAstroContainer({
+      integrations: options.integrations,
+      resolveClientModule,
+      viteServer
+    });
+
+    const loadModule = async (moduleId: string) => {
+      return (await viteServer.ssrLoadModule(
+        options.resolveComponentId?.(moduleId) ?? moduleId
+      )) as LoadedStoryModule;
+    };
+    const renderAstroStory = createAstroRenderHandler({
+      container: astroContainer,
+      sanitization: options.sanitization,
+      rulesConfigFilePath: options.storyRulesConfigFilePath,
+      resolveRulesConfigModule: () => rulesConfigModule,
+      loadModule: async (moduleId: string) => {
+        const loadedModule = await loadModule(moduleId);
+
+        return {
+          default: loadedModule.default
+        };
+      },
+      invalidateModuleGraph: () => {
+        viteServer.moduleGraph.invalidateAll();
+      }
+    });
+
+    return {
+      loadModule,
+      renderAstroStory,
+      close: () => viteServer.close()
+    };
+  } catch (error) {
+    await viteServer.close();
+    throw error;
+  }
+}
+
+/** Loads one Astro story module, merges its args, and renders the Astro component to HTML. */
+export async function renderProductionStoryToHtml(options: {
+  story: ProductionStoryEntry;
+  runtime: ProductionRenderRuntime;
+  resolveFrom: string;
+}) {
+  const storyModulePath = resolveProjectImportPath(options.story.importPath, options.resolveFrom);
+  const componentPath = resolveProjectImportPath(options.story.componentPath, options.resolveFrom);
+  const storyModule = await options.runtime.loadModule(storyModulePath);
+  const defaultStoryMeta = isRecord(storyModule.default) ? storyModule.default : {};
+  const selectedStoryExport = isRecord(storyModule[options.story.exportName])
+    ? storyModule[options.story.exportName]
+    : {};
+
+  if (typeof defaultStoryMeta.component !== 'function') {
+    throw new Error(
+      `Unable to prerender story "${options.story.id}". Missing default export component in ${options.story.importPath}.`
+    );
+  }
+
+  // Build-time prerender only supports stories that keep the meta-level Astro component.
+  if (selectedStoryExport.component && selectedStoryExport.component !== defaultStoryMeta.component) {
+    return undefined;
+  }
+
+  const storyArgs = mergeMetaArgsWithStoryArgs(
+    toRecord(defaultStoryMeta.args),
+    toRecord(selectedStoryExport.args)
+  );
+  const { componentArgs, storySlots } = separateStorySlots(storyArgs);
+
+  return options.runtime.renderAstroStory({
+    component: componentPath,
+    args: componentArgs,
+    slots: storySlots,
+    story: {
+      id: options.story.id,
+      title: options.story.title,
+      name: options.story.name
+    }
+  });
+}
+
+function resolveProjectImportPath(importPath: string, resolveFrom: string) {
+  if (importPath.startsWith('./') || importPath.startsWith('../')) {
+    return resolve(resolveFrom, importPath);
+  }
+
+  return importPath;
+}
+
+function mergeMetaArgsWithStoryArgs(
+  metaArgs: Record<string, unknown> | undefined,
+  storyArgs: Record<string, unknown> | undefined
+) {
+  return {
+    ...(metaArgs ?? {}),
+    ...(storyArgs ?? {})
+  };
+}
+
+function separateStorySlots(storyArgs: Record<string, unknown>) {
+  const componentArgs = { ...storyArgs };
+  const storySlots = componentArgs.slots;
+
+  delete componentArgs.slots;
+
+  if (!isRecord(storySlots)) {
+    return {
+      componentArgs,
+      storySlots: {}
+    };
+  }
+
+  return {
+    componentArgs,
+    storySlots: storySlots as Record<string, string>
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  return value;
+}

package/src/rules.test.ts

@@ -13,6 +13,10 @@ function createRulesConfig(config: StoryRulesConfig) {
   };
 }
 
+function getMockReplacement(selection: Awaited<ReturnType<typeof selectStoryRules>>, specifier: string) {
+  return selection.moduleMocks.get(specifier)?.replacement;
+}
+
 describe('story rules', () => {
   test('returns an empty selection when no rules are configured', async () => {
     const selection = await selectStoryRules({
@@ -43,7 +47,7 @@ describe('story rules', () => {
       }
     });
 
-    expect(selection.moduleMocks.get('~/lib/api')).toBe('~/lib/api.mock');
+    expect(getMockReplacement(selection, '~/lib/api')).toBe('~/lib/api.mock');
     expect(selection.cleanups).toHaveLength(0);
   });
 
@@ -66,7 +70,7 @@ describe('story rules', () => {
       }
     });
 
-    expect(selection.moduleMocks.get('~/service')).toBe('~/service.mock');
+    expect(getMockReplacement(selection, '~/service')).toBe('~/service.mock');
   });
 
   test('matches rules against /story/<id> style story identifiers', async () => {
@@ -86,7 +90,31 @@ describe('story rules', () => {
       }
     });
 
-    expect(selection.moduleMocks.get('~/store')).toBe('~/store.mock');
+    expect(getMockReplacement(selection, '~/store')).toBe('~/store.mock');
+  });
+
+  test('supports inline factory module mocks', async () => {
+    const selection = await selectStoryRules({
+      configModule: createRulesConfig({
+        rules: [
+          {
+            match: '*',
+            use: ({ mock }) => {
+              mock('~/lib/api', () => ({
+                fetchUser: async () => ({ id: 1, name: 'Storybook User' })
+              }));
+            }
+          }
+        ]
+      }),
+      story: {
+        id: 'components-card--default'
+      }
+    });
+
+    expect(getMockReplacement(selection, '~/lib/api')).toMatch(
+      /^virtual:storybook-astro-inline-module:/
+    );
   });
 
   test('collects cleanup functions from matching rules', async () => {
@@ -207,7 +235,7 @@ describe('story rules', () => {
       }
     });
 
-    expect(selection.moduleMocks.get('~/lib/api')).toBe(
+    expect(getMockReplacement(selection, '~/lib/api')).toBe(
       resolve('/repo/.storybook', './mocks/api.ts').replaceAll('\\', '/')
     );
   });
@@ -251,4 +279,24 @@ describe('story rules', () => {
       'Story rule mock replacement uses a relative path, but rules config path is unavailable.'
     );
   });
+
+  test('throws when a mock factory returns a non-object value', async () => {
+    await expect(
+      selectStoryRules({
+        configModule: createRulesConfig({
+          rules: [
+            {
+              match: '*',
+              use: ({ mock }) => {
+                mock('~/lib/api', () => 'bad' as never);
+              }
+            }
+          ]
+        }),
+        story: {
+          id: 'components-card--default'
+        }
+      })
+    ).rejects.toThrow('Story rule mock factory must return an object of module exports.');
+  });
 });

package/src/rules.ts

@@ -1,12 +1,26 @@
 import { dirname, isAbsolute, resolve } from 'node:path';
+import {
+  createInlineStoryModuleMock,
+  createPathStoryModuleMock,
+  type StoryModuleMockEntry,
+  type StoryModuleMockFactoryResult
+} from './module-mocks.ts';
 import type { RenderStoryInput } from './types.ts';
 
 export type StoryRuleCleanup = () => void | Promise<void>;
 type StoryRuleUseResult = void | StoryRuleCleanup | Promise<void | StoryRuleCleanup>;
 
+export type StoryRuleMockFactory =
+  () => StoryModuleMockFactoryResult | Promise<StoryModuleMockFactoryResult>;
+
+export type StoryRuleMock = {
+  (specifier: string, replacement: string): void;
+  (specifier: string, factory: StoryRuleMockFactory): void;
+};
+
 export type StoryRuleUseContext = {
   story: StoryRuleStory;
-  mock: (specifier: string, replacement: string) => void;
+  mock: StoryRuleMock;
 };
 
 export type StoryRuleUse = (context: StoryRuleUseContext) => StoryRuleUseResult;
@@ -34,12 +48,12 @@ export type StoryRuleSelectionInput = {
 };
 
 export type StoryRuleSelection = {
-  moduleMocks: Map<string, string>;
+  moduleMocks: Map<string, StoryModuleMockEntry>;
   cleanups: StoryRuleCleanup[];
 };
 
 type MutableStoryRuleSelection = {
-  moduleMocks: Map<string, string>;
+  moduleMocks: Map<string, StoryModuleMockEntry>;
   cleanups: StoryRuleCleanup[];
 };
 
@@ -62,20 +76,45 @@ export async function selectStoryRules(
     const uses = Array.isArray(rule.use) ? rule.use : [rule.use];
 
     for (const use of uses) {
+      const pendingModuleMocks: Promise<void>[] = [];
+
       if (typeof use !== 'function') {
         throw new Error('Each story rule "use" entry must be a function.');
       }
 
       const cleanup = await use({
         story,
-        mock: (specifier, replacement) => {
+        mock: ((specifier, replacementOrFactory) => {
           const normalizedSpecifier = normalizeMockSpecifier(specifier);
-          const normalizedReplacement = normalizeMockReplacement(replacement, input.configFilePath);
 
-          selection.moduleMocks.set(normalizedSpecifier, normalizedReplacement);
-        }
+          if (typeof replacementOrFactory === 'function') {
+            pendingModuleMocks.push(
+              Promise.resolve(replacementOrFactory()).then((exportsObject) => {
+                selection.moduleMocks.set(
+                  normalizedSpecifier,
+                  createInlineStoryModuleMock(normalizeMockFactoryResult(exportsObject))
+                );
+
+                return undefined;
+              })
+            );
+
+            return;
+          }
+
+          const normalizedReplacement = normalizeMockReplacement(
+            replacementOrFactory,
+            input.configFilePath
+          );
+
+          selection.moduleMocks.set(normalizedSpecifier, createPathStoryModuleMock(normalizedReplacement));
+        }) as StoryRuleMock
       });
 
+      if (pendingModuleMocks.length > 0) {
+        await Promise.all(pendingModuleMocks);
+      }
+
       if (cleanup !== undefined) {
         if (typeof cleanup !== 'function') {
           throw new Error('Story rule "use" must return either nothing or a cleanup function.');
@@ -331,6 +370,14 @@ function normalizeMockReplacement(value: unknown, configFilePath?: string): stri
   return normalizedValue;
 }
 
+function normalizeMockFactoryResult(value: unknown): StoryModuleMockFactoryResult {
+  if (!isRecord(value)) {
+    throw new Error('Story rule mock factory must return an object of module exports.');
+  }
+
+  return value;
+}
+
 function slugify(input: string): string {
   return input
     .trim()

package/src/server/index.ts

@@ -1,20 +1,24 @@
+/// <reference path="../virtual.d.ts" />
+
 import { timingSafeEqual } from 'node:crypto';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
-import type { HandlerProps } from '../middleware.ts';
-import { handlerFactory } from '../middleware.ts';
-import astroFiles from 'virtual:astro-files';
-import sanitization from 'virtual:storybook-astro-sanitization-config';
-import storyRulesConfigModule, {
-  storybookAstroStoryRulesConfigFilePath
-} from 'virtual:storybook-astro-story-rules-config';
+import type { HandlerProps } from '../astroRenderHandler.ts';
+import { createProductionRenderRuntime } from '../productionRenderRuntime.ts';
+import sanitization from 'virtual:storybook-astro/sanitize-config';
 import {
   storybookAstroServerAuthHeader,
   storybookAstroServerAuthToken
-} from 'virtual:storybook-astro-server-auth-config';
+} from 'virtual:storybook-astro/server-auth';
+import {
+  integrations,
+  runtimeConfig
+} from 'virtual:storybook-astro/server-runtime';
 
 const app = new Hono();
-const renderHandlerPromise = createRenderHandler();
+const renderAstroStoryPromise = createAstroStoryRenderer();
 
 app.use(
   '*',
@@ -33,46 +37,62 @@ app.post('/render', async (context) => {
   }
 
   const input = (await context.req.json()) as Partial<HandlerProps>;
-  const renderHandler = await renderHandlerPromise;
-  const html = await renderHandler({
+  const renderAstroStory = await renderAstroStoryPromise;
+  const html = await renderAstroStory({
     component: input.component ?? '',
     args: input.args ?? {},
     slots: input.slots ?? {},
     story: input.story
   });
 
-  return context.text(html);
+  // The server runtime renders against source modules, then rewrites the HTML
+  // so the browser only sees built asset URLs and matching stylesheets.
+  return context.text(addStaticStylesheets(rewriteBuiltModulePaths(html)));
 });
 
 export default app;
 
-async function createRenderHandler() {
-  return handlerFactory([], {
+/** Creates the server-mode Astro story renderer from the shared production runtime. */
+async function createAstroStoryRenderer() {
+  const snapshotRoot = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    runtimeConfig.snapshotDirName
+  );
+  const storyRulesConfigFilePath = runtimeConfig.storyRulesConfigRelativePath
+    ? resolve(snapshotRoot, runtimeConfig.storyRulesConfigRelativePath)
+    : undefined;
+  const runtime = await createProductionRenderRuntime({
+    integrations,
     sanitization: sanitization ?? undefined,
-    rulesConfigFilePath: storybookAstroStoryRulesConfigFilePath,
-    resolveRulesConfigModule: () => storyRulesConfigModule,
-    loadModule: async (componentId) => {
-      const component = astroFiles[componentId as keyof typeof astroFiles];
-
-      if (!component) {
-        throw new Error(
-          `Unable to resolve Astro component "${componentId}" in the server build output.`
-        );
-      }
-
-      return {
-        default: component
-      };
-    }
+    storyRulesConfigFilePath,
+    staticModuleMap: runtimeConfig.staticModuleMap,
+    trackedSpecifiers: new Set(runtimeConfig.trackedSpecifiers),
+    resolveFrom: snapshotRoot,
+    resolveComponentId: (componentId: string) =>
+      resolveSnapshotComponentPath(snapshotRoot, componentId)
   });
+
+  return runtime.renderAstroStory;
+}
+
+/** Resolves one original component id to the copied file inside the runtime snapshot. */
+function resolveSnapshotComponentPath(snapshotRoot: string, componentId: string) {
+  const snapshotComponentPath = runtimeConfig.componentPathMap[componentId];
+
+  if (snapshotComponentPath) {
+    return resolve(snapshotRoot, snapshotComponentPath);
+  }
+
+  return componentId;
 }
 
+/** Checks the incoming auth header against the configured render-server token. */
 function isRequestAuthorized(headerValue: string | undefined) {
   if (!storybookAstroServerAuthToken) {
     return true;
   }
 
-  const normalizedHeaderValue = normalizeHeaderValue(headerValue);
+  const normalizedHeaderValue = normalizeAuthHeaderValue(headerValue);
 
   if (!normalizedHeaderValue) {
     return false;
@@ -81,7 +101,8 @@ function isRequestAuthorized(headerValue: string | undefined) {
   return isSecureEqual(normalizedHeaderValue, storybookAstroServerAuthToken);
 }
 
-function normalizeHeaderValue(value: string | undefined) {
+/** Normalizes auth header values so bearer and raw token formats compare the same way. */
+function normalizeAuthHeaderValue(value: string | undefined) {
   if (!value) {
     return undefined;
   }
@@ -99,6 +120,7 @@ function normalizeHeaderValue(value: string | undefined) {
   return trimmedValue;
 }
 
+/** Compares auth tokens without leaking length-matched timing differences. */
 function isSecureEqual(actual: string, expected: string) {
   const actualBuffer = Buffer.from(actual);
   const expectedBuffer = Buffer.from(expected);
@@ -109,3 +131,51 @@ function isSecureEqual(actual: string, expected: string) {
 
   return timingSafeEqual(actualBuffer, expectedBuffer);
 }
+
+/** Rewrites source module paths in rendered HTML to the built asset paths emitted by Storybook. */
+function rewriteBuiltModulePaths(html: string) {
+  let output = html;
+  const entries = Object.entries(runtimeConfig.staticModuleMap).sort(
+    ([left], [right]) => right.length - left.length
+  );
+
+  for (const [sourcePath, builtPath] of entries) {
+    output = output.split(sourcePath).join(builtPath);
+    output = output.split(toFsPath(sourcePath)).join(builtPath);
+  }
+
+  return output;
+}
+
+/** Prepends stylesheet links for any built framework chunks referenced by the rendered HTML. */
+function addStaticStylesheets(html: string) {
+  const stylesheets = new Set<string>();
+
+  for (const [sourcePath, cssPaths] of Object.entries(runtimeConfig.staticCssMap)) {
+    const builtModulePath = runtimeConfig.staticModuleMap[sourcePath];
+
+    // Match either the original source path or the rewritten built module URL.
+    if (!html.includes(sourcePath) && (!builtModulePath || !html.includes(builtModulePath))) {
+      continue;
+    }
+
+    cssPaths.forEach((cssPath) => stylesheets.add(cssPath));
+  }
+
+  if (stylesheets.size === 0) {
+    return html;
+  }
+
+  const stylesheetTags = Array.from(stylesheets)
+    .map((href) => `<link rel="stylesheet" href="${href}">`)
+    .join('');
+
+  return `${stylesheetTags}${html}`;
+}
+
+/** Converts one source file path into the Vite /@fs/ URL form used during SSR. */
+function toFsPath(sourcePath: string) {
+  const normalizedPath = sourcePath.replace(/\\/g, '/');
+
+  return normalizedPath.startsWith('/') ? `/@fs${normalizedPath}` : `/@fs/${normalizedPath}`;
+}

package/src/storyRulesRuntime.ts

@@ -0,0 +1,34 @@
+import { withStoryModuleMocks } from './module-mocks.ts';
+import { selectStoryRules, withStoryRuleCleanups, type StoryRuleSelection } from './rules.ts';
+import type { RenderStoryInput } from './types.ts';
+
+export type ResolveRulesConfigModule = () => unknown | Promise<unknown>;
+
+type RunWithStoryRulesOptions = {
+  story?: RenderStoryInput;
+  rulesConfigFilePath?: string;
+  resolveRulesConfigModule?: ResolveRulesConfigModule;
+  invalidateModuleGraph?: () => void;
+};
+
+export async function runWithStoryRules<T>(
+  options: RunWithStoryRulesOptions,
+  callback: (selection: StoryRuleSelection) => Promise<T>
+): Promise<T> {
+  const rulesConfigModule = options.resolveRulesConfigModule
+    ? await options.resolveRulesConfigModule()
+    : undefined;
+  const selectedRules = await selectStoryRules({
+    configModule: rulesConfigModule,
+    configFilePath: options.rulesConfigFilePath,
+    story: options.story
+  });
+
+  if (selectedRules.moduleMocks.size > 0) {
+    options.invalidateModuleGraph?.();
+  }
+
+  return withStoryRuleCleanups(selectedRules.cleanups, async () => {
+    return withStoryModuleMocks(selectedRules.moduleMocks, async () => callback(selectedRules));
+  });
+}