@storybook-astro/framework 1.0.3 → 1.1.1

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { CompatibleString, Options } from 'storybook/internal/types';
+import type { CompatibleString, Options, StorybookConfig as StorybookConfigBase } from 'storybook/internal/types';
 import type { InlineConfig } from 'vite';
 import type { Integration } from './integrations/index.ts';
 import type { SanitizationOptions } from './lib/sanitization.ts';
@@ -7,6 +7,13 @@ import type { StoryRulesOptions } from './rules-options.ts';
 type FrameworkName = CompatibleString<'@storybook-astro/framework'>;
 
 export type { Integration, SanitizationOptions, StoryRulesOptions };
+export type RenderMode = 'server' | 'static';
+
+export type ServerBuildOptions = {
+  serverUrl?: string;
+  authToken?: string;
+  authHeader?: string;
+};
 
 export type RenderStoryInput = {
   id: string;
@@ -14,13 +21,26 @@ export type RenderStoryInput = {
   name?: string;
 };
 
-export type FrameworkOptions = {
+type BaseFrameworkOptions = {
   integrations?: Integration[];
   sanitization?: SanitizationOptions;
-  storyRules?: StoryRulesOptions;
   resolveFrom?: string;
 };
 
+type ServerFrameworkOptions = BaseFrameworkOptions & {
+  renderMode?: 'server';
+  storyRules?: StoryRulesOptions;
+  server?: ServerBuildOptions;
+};
+
+type StaticFrameworkOptions = BaseFrameworkOptions & {
+  renderMode: 'static';
+  storyRules?: StoryRulesOptions;
+  server?: never;
+};
+
+export type FrameworkOptions = ServerFrameworkOptions | StaticFrameworkOptions;
+
 type StorybookConfigFramework = {
   framework: {
     name: FrameworkName;
@@ -28,10 +48,10 @@ type StorybookConfigFramework = {
   };
 };
 
-export type StorybookConfig = StorybookConfigFramework;
-
 type ViteFinal = (config: InlineConfig, options: Options) => InlineConfig | Promise<InlineConfig>;
 
 export type StorybookConfigVite = {
   viteFinal?: ViteFinal;
 };
+
+export type StorybookConfig = Omit<StorybookConfigBase, 'framework'> & StorybookConfigFramework & StorybookConfigVite;

package/src/virtual.d.ts

@@ -5,4 +5,41 @@ declare module 'virtual:astro-container-renderers' {
   export function resolveClientModules(specifier: string): string | undefined;
 }
 
+declare module 'virtual:astro-files' {
+  const astroFiles: Record<string, unknown>;
+
+  export default astroFiles;
+}
+
+declare module 'virtual:storybook-astro-renderer' {
+  import type { RenderComponentInput, RenderResponseMessage } from '@storybook-astro/renderer/types';
+
+  export function render(
+    input: RenderComponentInput,
+    timeoutMs?: number
+  ): Promise<RenderResponseMessage['data']>;
+  export function init(): void;
+  export function applyStyles(): void;
+}
+
+declare module 'virtual:storybook-astro-sanitization-config' {
+  import type { SanitizationOptions } from './lib/sanitization.ts';
+
+  const sanitization: SanitizationOptions | undefined;
+
+  export default sanitization;
+}
+
+declare module 'virtual:storybook-astro-story-rules-config' {
+  const configModule: unknown;
+
+  export default configModule;
+  export const storybookAstroStoryRulesConfigFilePath: string | undefined;
+}
+
+declare module 'virtual:storybook-astro-server-auth-config' {
+  export const storybookAstroServerAuthToken: string | undefined;
+  export const storybookAstroServerAuthHeader: string;
+}
+
 declare module 'virtual:storybook-renderer-fallback' {}

package/src/vite/astroFilesVirtualModulePlugin.ts

@@ -0,0 +1,36 @@
+import type { Plugin } from 'vite';
+import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+
+type ImportRecord = {
+  id: string;
+  file: string;
+  importStatement: string;
+};
+
+export function astroFilesVirtualModulePlugin(astroComponents: string[]): Plugin {
+  return createVirtualModulePlugin({
+    pluginName: 'storybook-astro:virtual-astro-files',
+    virtualModuleId: 'virtual:astro-files',
+    load() {
+      const imports = astroComponents.reduce<ImportRecord[]>((records, file, index) => {
+        const moduleId = `_astroFile${index}`;
+
+        return [
+          ...records,
+          {
+            id: moduleId,
+            file,
+            importStatement: `import ${moduleId} from '${file}';`
+          }
+        ];
+      }, []);
+
+      return [
+        imports.map(({ importStatement }) => importStatement).join('\n'),
+        'export default {',
+        imports.map(({ file, id }) => `'${file}': ${id}`).join(',\n'),
+        '};'
+      ].join('\n');
+    }
+  });
+}

package/src/vite/createVirtualModulePlugin.ts

@@ -1,4 +1,4 @@
-import type { PluginOption } from 'vite';
+import type { Plugin } from 'vite';
 
 type CreateVirtualModulePluginOptions = {
   pluginName: string;
@@ -6,7 +6,7 @@ type CreateVirtualModulePluginOptions = {
   load: (id: string) => string | Promise<string> | undefined;
 };
 
-export function createVirtualModulePlugin(options: CreateVirtualModulePluginOptions): PluginOption {
+export function createVirtualModulePlugin(options: CreateVirtualModulePluginOptions): Plugin {
   const resolvedVirtualModuleId = `\0${options.virtualModuleId}`;
 
   return {
@@ -21,5 +21,5 @@ export function createVirtualModulePlugin(options: CreateVirtualModulePluginOpti
         return options.load(id);
       }
     }
-  } satisfies PluginOption;
+  } satisfies Plugin;
 }

package/src/vite/storybookAstroRulesConfigVirtualModulePlugin.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from 'vite';
+import type { StoryRulesOptions } from '../rules-options.ts';
+import { resolveRulesConfigFilePath } from '../rules-options.ts';
+import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+
+export const STORYBOOK_ASTRO_STORY_RULES_CONFIG_VIRTUAL_MODULE_ID =
+  'virtual:storybook-astro-story-rules-config';
+
+export function storybookAstroStoryRulesConfigVirtualModulePlugin(
+  options?: StoryRulesOptions,
+  resolveFrom = process.cwd()
+): Plugin {
+  return createVirtualModulePlugin({
+    pluginName: 'storybook-astro:virtual-story-rules-config',
+    virtualModuleId: STORYBOOK_ASTRO_STORY_RULES_CONFIG_VIRTUAL_MODULE_ID,
+    load() {
+      const configFilePath = resolveRulesConfigFilePath(options, resolveFrom);
+
+      if (!configFilePath) {
+        return [
+          'const storybookAstroStoryRulesConfig = { rules: [] };',
+          'export default storybookAstroStoryRulesConfig;',
+          'export const storybookAstroStoryRulesConfigFilePath = undefined;'
+        ].join('\n');
+      }
+
+      const importPath = JSON.stringify(configFilePath.replace(/\\/g, '/'));
+      const configPath = JSON.stringify(configFilePath.replace(/\\/g, '/'));
+
+      return [
+        `import * as storybookAstroStoryRulesConfigModule from ${importPath};`,
+        'export default storybookAstroStoryRulesConfigModule;',
+        `export const storybookAstroStoryRulesConfigFilePath = ${configPath};`
+      ].join('\n');
+    }
+  });
+}

package/src/vite/storybookAstroSanitizationConfigVirtualModulePlugin.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from 'vite';
+import type { SanitizationOptions } from '../lib/sanitization.ts';
+import { serializeSanitizationOptions } from '../lib/sanitization.ts';
+import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+
+export const STORYBOOK_ASTRO_SANITIZATION_CONFIG_VIRTUAL_MODULE_ID =
+  'virtual:storybook-astro-sanitization-config';
+
+export function storybookAstroSanitizationConfigVirtualModulePlugin(
+  options?: SanitizationOptions
+): Plugin {
+  return createVirtualModulePlugin({
+    pluginName: 'storybook-astro:virtual-sanitization-config',
+    virtualModuleId: STORYBOOK_ASTRO_SANITIZATION_CONFIG_VIRTUAL_MODULE_ID,
+    load() {
+      const serializedConfig = serializeSanitizationOptions(options);
+
+      return `export default ${serializedConfig};`;
+    }
+  });
+}

package/src/vite/storybookAstroServerAuthConfigVirtualModulePlugin.test.ts

@@ -0,0 +1,71 @@
+import type { PluginOption } from 'vite';
+import { describe, expect, test } from 'vitest';
+import {
+  STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID,
+  storybookAstroServerAuthConfigVirtualModulePlugin
+} from './storybookAstroServerAuthConfigVirtualModulePlugin.ts';
+
+function getPlugin(pluginOption: PluginOption) {
+  if (Array.isArray(pluginOption)) {
+    throw new Error('Expected a single plugin object, but got a plugin array.');
+  }
+
+  if (!pluginOption || typeof pluginOption !== 'object') {
+    throw new Error('Expected plugin option to be an object.');
+  }
+
+  return pluginOption;
+}
+
+function getHookHandler<T extends (...args: unknown[]) => unknown>(hook: unknown): T {
+  if (typeof hook === 'function') {
+    return hook as T;
+  }
+
+  if (
+    typeof hook === 'object' &&
+    hook !== null &&
+    'handler' in hook &&
+    typeof (hook as { handler?: unknown }).handler === 'function'
+  ) {
+    return (hook as { handler: T }).handler;
+  }
+
+  throw new Error('Expected hook to be a function or an object with a handler function.');
+}
+
+describe('storybookAstroServerAuthConfigVirtualModulePlugin', () => {
+  test('normalizes auth token and header values', async () => {
+    const plugin = getPlugin(
+      storybookAstroServerAuthConfigVirtualModulePlugin({
+        authToken: '  test-token  ',
+        authHeader: '  X-Storybook-Token  '
+      })
+    );
+    const resolveId = getHookHandler<(id: string) => string | undefined>(plugin.resolveId);
+    const load = getHookHandler<(id: string) => Promise<string | undefined>>(plugin.load);
+    const resolvedId = resolveId(STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID);
+
+    expect(resolvedId).toBe(`\0${STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID}`);
+    await expect(load(resolvedId!)).resolves.toBe(
+      'export const storybookAstroServerAuthToken = "test-token";\n' +
+        'export const storybookAstroServerAuthHeader = "x-storybook-token";'
+    );
+  });
+
+  test('falls back to authorization header and undefined token', async () => {
+    const plugin = getPlugin(
+      storybookAstroServerAuthConfigVirtualModulePlugin({
+        authToken: '   '
+      })
+    );
+    const load = getHookHandler<(id: string) => Promise<string | undefined>>(plugin.load);
+
+    await expect(
+      load(`\0${STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID}`)
+    ).resolves.toBe(
+      'export const storybookAstroServerAuthToken = undefined;\n' +
+        'export const storybookAstroServerAuthHeader = "authorization";'
+    );
+  });
+});

package/src/vite/storybookAstroServerAuthConfigVirtualModulePlugin.ts

@@ -0,0 +1,42 @@
+import type { Plugin } from 'vite';
+import type { ServerBuildOptions } from '../types.ts';
+import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+
+export const STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID =
+  'virtual:storybook-astro-server-auth-config';
+
+export function storybookAstroServerAuthConfigVirtualModulePlugin(
+  options?: ServerBuildOptions
+): Plugin {
+  const authToken = normalizeOptionalString(options?.authToken);
+  const authHeader = normalizeAuthHeader(options?.authHeader);
+
+  return createVirtualModulePlugin({
+    pluginName: 'storybook-astro:virtual-server-auth-config',
+    virtualModuleId: STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID,
+    load() {
+      return [
+        `export const storybookAstroServerAuthToken = ${
+          authToken ? JSON.stringify(authToken) : 'undefined'
+        };`,
+        `export const storybookAstroServerAuthHeader = ${JSON.stringify(authHeader)};`
+      ].join('\n');
+    }
+  });
+}
+
+function normalizeOptionalString(value: string | undefined) {
+  if (!value) {
+    return undefined;
+  }
+
+  const normalizedValue = value.trim();
+
+  return normalizedValue || undefined;
+}
+
+function normalizeAuthHeader(value: string | undefined) {
+  const normalizedValue = normalizeOptionalString(value);
+
+  return (normalizedValue ?? 'authorization').toLowerCase();
+}

package/src/vitePluginAstroBuildPrerender.ts

@@ -9,11 +9,11 @@ import type { Integration } from './integrations/index.ts';
 import { ssrLoadModuleWithFsFallback } from './lib/ssr-load-module-with-fs-fallback.ts';
 import { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';
 import { resolveStoryModuleMock, withStoryModuleMocks } from './module-mocks.ts';
-import { applyMswHandlers } from './msw.ts';
 import { resolveRulesConfigFilePath } from './rules-options.ts';
-import { selectStoryRules } from './rules.ts';
+import { selectStoryRules, withStoryRuleCleanups } from './rules.ts';
 import type { FrameworkOptions } from './types.ts';
 import { vitePluginAstroFontsFallback } from './vitePluginAstroFontsFallback.ts';
+import { vitePluginAstroIntegrationOptsFallback } from './vitePluginAstroIntegrationOptsFallback.ts';
 import { vitePluginAstroRoutesFallback } from './vitePluginAstroRoutesFallback.ts';
 import { vitePluginAstroVueFallback } from './vitePluginAstroVueFallback.ts';
 
@@ -218,7 +218,6 @@ async function prerenderStories(options: {
       const selectedRules = await selectStoryRules({
         configModule: rulesConfigModule,
         configFilePath: options.storyRulesConfigFilePath,
-        mode: 'production',
         story: {
           id: story.id,
           title: story.title,
@@ -226,42 +225,47 @@ async function prerenderStories(options: {
         }
       });
 
-      await applyMswHandlers(selectedRules.mswHandlers);
-
       if (selectedRules.moduleMocks.size > 0) {
         viteServer.moduleGraph.invalidateAll();
       }
 
-      const html = await withStoryModuleMocks(selectedRules.moduleMocks, async () => {
-        const modulePath = resolveImportPath(story.importPath, options.resolveFrom);
-        const storyModule = await viteServer.ssrLoadModule(modulePath);
-        const meta = isRecord(storyModule.default) ? storyModule.default : {};
-        const storyExport = isRecord(storyModule[story.exportName]) ? storyModule[story.exportName] : {};
+      const html = await withStoryRuleCleanups(selectedRules.cleanups, async () => {
+        return withStoryModuleMocks(selectedRules.moduleMocks, async () => {
+          const modulePath = resolveImportPath(story.importPath, options.resolveFrom);
+          const storyModule = await viteServer.ssrLoadModule(modulePath);
+          const meta = isRecord(storyModule.default) ? storyModule.default : {};
+          const storyExport = isRecord(storyModule[story.exportName])
+            ? storyModule[story.exportName]
+            : {};
+
+          if (typeof meta.component !== 'function') {
+            throw new Error(
+              `Unable to prerender story "${story.id}". Missing default export component in ${story.importPath}.`
+            );
+          }
 
-        if (typeof meta.component !== 'function') {
-          throw new Error(
-            `Unable to prerender story "${story.id}". Missing default export component in ${story.importPath}.`
-          );
-        }
+          if (storyExport.component && storyExport.component !== meta.component) {
+            return undefined;
+          }
 
-        if (storyExport.component && storyExport.component !== meta.component) {
-          return undefined;
-        }
+          const mergedArgs = mergeStoryArgs(toRecord(meta.args), toRecord(storyExport.args));
+          const { args, slots } = separateSlots(mergedArgs);
+          const processedArgs = await processImageMetadata(args);
+          const sanitizedPayload = sanitizeRenderPayload(
+            {
+              args: processedArgs,
+              slots
+            },
+            sanitizationOptions
+          );
 
-        const mergedArgs = mergeStoryArgs(toRecord(meta.args), toRecord(storyExport.args));
-        const { args, slots } = separateSlots(mergedArgs);
-        const processedArgs = await processImageMetadata(args);
-        const sanitizedPayload = sanitizeRenderPayload(
-          {
-            args: processedArgs,
-            slots
-          },
-          sanitizationOptions
-        );
-
-        return container.renderToString(patchCreateAstroCompat(meta.component), {
-          props: sanitizedPayload.args,
-          slots: sanitizedPayload.slots
+          return container.renderToString(
+            patchCreateAstroCompat(meta.component) as Parameters<typeof container.renderToString>[0],
+            {
+              props: sanitizedPayload.args,
+              slots: sanitizedPayload.slots
+            }
+          );
         });
       });
 
@@ -281,14 +285,18 @@ async function createStorySsrServer(
   trackedSpecifiers: Set<string>,
   resolveFrom: string
 ) {
-  const { getViteConfig } = await importAstroConfig(resolveFrom);
+  const { getViteConfig, passthroughImageService } = await importAstroConfig(resolveFrom);
   const astroConfig = await getViteConfig(
     { root: resolveFrom },
     {
       configFile: false,
       integrations: await Promise.all(
         integrations.map((integration) => integration.loadIntegration(resolveFrom))
-      )
+      ),
+      // Use the passthrough image service so nested components that use <Image>
+      // from astro:assets render as plain <img> tags without triggering image
+      // optimization (which fails in the Storybook SSR context).
+      image: { service: passthroughImageService() }
     }
   )({
     mode: 'production',
@@ -303,6 +311,7 @@ async function createStorySsrServer(
     plugins: [
       createProjectAstroResolutionPlugin(resolveFrom),
       vitePluginAstroFontsFallback(),
+      vitePluginAstroIntegrationOptsFallback(),
       vitePluginAstroVueFallback(),
       vitePluginAstroRoutesFallback(),
       {
@@ -364,7 +373,7 @@ async function addContainerRenderers(
           renderer: {
             ...renderer,
             name: serverRenderer.name
-          }
+          } as Parameters<typeof container.addServerRenderer>[0]['renderer']
         });
       } else {
         container.addServerRenderer({
@@ -633,7 +642,11 @@ async function processImageMetadata(
 
   for (const [key, value] of Object.entries(args)) {
     if (isImageMetadata(value)) {
-      processed[key] = convertImageMetadataToUrl(value);
+      // Keep ImageMetadata as a plain object — Astro's image service checks
+      // isESMImportedImage (typeof src === 'object') and skips the /@fs/ string
+      // validation that throws LocalImageUsedWrongly. Converting to a URL string
+      // causes that error when the string starts with /@fs/.
+      processed[key] = value;
 
       continue;
     }
@@ -642,7 +655,7 @@ async function processImageMetadata(
       processed[key] = await Promise.all(
         value.map(async (item) => {
           if (isImageMetadata(item)) {
-            return convertImageMetadataToUrl(item);
+            return item;
           }
 
           if (isRecord(item)) {
@@ -676,20 +689,6 @@ function isImageMetadata(value: unknown): value is Record<string, unknown> {
   );
 }
 
-function convertImageMetadataToUrl(imageMetadata: Record<string, unknown>): string {
-  const src = imageMetadata.src;
-  const fsPath = imageMetadata.fsPath;
-
-  if (typeof src === 'string') {
-    return src;
-  }
-
-  if (typeof fsPath === 'string') {
-    return fsPath;
-  }
-
-  return String(imageMetadata);
-}
 
 function createProjectAstroResolutionPlugin(resolveFrom: string): Plugin {
   const require = createRequire(import.meta.url);