@storybook-astro/framework 1.0.2 → 1.1.0

package/src/renderer/renderer-static.ts

@@ -0,0 +1,62 @@
+import type { RenderComponentInput, RenderResponseMessage } from '@storybook-astro/renderer/types';
+
+const PRERENDERED_STORIES_FILE = 'astro-prerendered-stories.json';
+
+let prerenderedStoriesPromise: Promise<Record<string, string>> | undefined;
+
+export async function render(data: RenderComponentInput) {
+  // eslint-disable-next-line n/no-unsupported-features/node-builtins
+  const id = crypto.randomUUID();
+  const storyId = data.story?.id;
+
+  if (!storyId) {
+    throw new Error(
+      'Astro static renderer expected a story id, but none was provided in the render payload.'
+    );
+  }
+
+  const prerenderedStories = await loadPrerenderedStories();
+  const html = prerenderedStories[storyId];
+
+  if (html === undefined) {
+    throw new Error(
+      `No prerendered HTML was found for story "${storyId}". Rebuild Storybook static output.`
+    );
+  }
+
+  return {
+    id,
+    html
+  } satisfies RenderResponseMessage['data'];
+}
+
+export function init() {
+  return;
+}
+
+export function applyStyles() {
+  return;
+}
+
+async function loadPrerenderedStories() {
+  if (!prerenderedStoriesPromise) {
+    const jsonPath = resolvePrerenderedStoriesUrl();
+
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins
+    prerenderedStoriesPromise = fetch(jsonPath).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(
+          `Failed to load ${PRERENDERED_STORIES_FILE}. Received ${response.status} ${response.statusText}.`
+        );
+      }
+
+      return (await response.json()) as Record<string, string>;
+    });
+  }
+
+  return prerenderedStoriesPromise;
+}
+
+function resolvePrerenderedStoriesUrl() {
+  return new URL(PRERENDERED_STORIES_FILE, window.location.href).toString();
+}

package/src/rules.test.ts

@@ -1,7 +1,11 @@
 import { resolve } from 'node:path';
-import type { RequestHandler } from 'msw';
 import { describe, expect, test } from 'vitest';
-import { defineStoryRules, selectStoryRules, type StoryRulesConfig } from './rules.ts';
+import {
+  defineStoryRules,
+  selectStoryRules,
+  withStoryRuleCleanups,
+  type StoryRulesConfig
+} from './rules.ts';
 
 function createRulesConfig(config: StoryRulesConfig) {
   return {
@@ -13,14 +17,13 @@ describe('story rules', () => {
   test('returns an empty selection when no rules are configured', async () => {
     const selection = await selectStoryRules({
       configModule: undefined,
-      mode: 'development',
       story: {
         id: 'components-card--default'
       }
     });
 
     expect(selection.moduleMocks.size).toBe(0);
-    expect(selection.mswHandlers).toEqual([]);
+    expect(selection.cleanups).toEqual([]);
   });
 
   test('matches rules against story id and applies module mocks', async () => {
@@ -35,14 +38,13 @@ describe('story rules', () => {
           }
         ]
       }),
-      mode: 'development',
       story: {
         id: 'components-card--default'
       }
     });
 
     expect(selection.moduleMocks.get('~/lib/api')).toBe('~/lib/api.mock');
-    expect(selection.mswHandlers).toHaveLength(0);
+    expect(selection.cleanups).toHaveLength(0);
   });
 
   test('matches rules against title and story name paths', async () => {
@@ -57,7 +59,6 @@ describe('story rules', () => {
           }
         ]
       }),
-      mode: 'development',
       story: {
         id: 'guides-getting-started--default-state',
         title: 'Guides/Getting Started',
@@ -80,7 +81,6 @@ describe('story rules', () => {
           }
         ]
       }),
-      mode: 'development',
       story: {
         id: '/story/components-card--default'
       }
@@ -89,28 +89,102 @@ describe('story rules', () => {
     expect(selection.moduleMocks.get('~/store')).toBe('~/store.mock');
   });
 
-  test('collects MSW handlers from matching rules', async () => {
-    const firstHandler = {} as RequestHandler;
-    const secondHandler = {} as RequestHandler;
+  test('collects cleanup functions from matching rules', async () => {
+    const cleanup = () => undefined;
 
     const selection = await selectStoryRules({
       configModule: createRulesConfig({
         rules: [
           {
             match: '*',
-            use: ({ msw }) => {
-              msw.use(firstHandler, secondHandler);
+            use: () => {
+              return cleanup;
             }
           }
         ]
       }),
-      mode: 'production',
       story: {
         id: 'components-card--default'
       }
     });
 
-    expect(selection.mswHandlers).toEqual([firstHandler, secondHandler]);
+    expect(selection.cleanups).toEqual([cleanup]);
+  });
+
+  test('runs cleanups after successful execution in reverse order', async () => {
+    const sequence: string[] = [];
+
+    await withStoryRuleCleanups(
+      [
+        () => {
+          sequence.push('cleanup:first');
+        },
+        async () => {
+          sequence.push('cleanup:second');
+        }
+      ],
+      async () => {
+        sequence.push('render');
+      }
+    );
+
+    expect(sequence).toEqual(['render', 'cleanup:second', 'cleanup:first']);
+  });
+
+  test('runs cleanups when execution throws', async () => {
+    const sequence: string[] = [];
+
+    await expect(
+      withStoryRuleCleanups(
+        [
+          () => {
+            sequence.push('cleanup');
+          }
+        ],
+        async () => {
+          sequence.push('render');
+          throw new Error('render failed');
+        }
+      )
+    ).rejects.toThrow('render failed');
+
+    expect(sequence).toEqual(['render', 'cleanup']);
+  });
+
+  test('throws when use returns a non-function value', async () => {
+    await expect(
+      selectStoryRules({
+        configModule: createRulesConfig({
+          rules: [
+            {
+              match: '*',
+              use: () => 'nope' as never
+            }
+          ]
+        }),
+        story: {
+          id: 'components-card--default'
+        }
+      })
+    ).rejects.toThrow('Story rule "use" must return either nothing or a cleanup function.');
+  });
+
+  test('aggregates cleanup failures', async () => {
+    await expect(
+      withStoryRuleCleanups(
+        [
+          () => {
+            throw new Error('first cleanup failed');
+          },
+          () => {
+            throw new Error('second cleanup failed');
+          }
+        ],
+        async () => undefined
+      )
+    ).rejects.toMatchObject({
+      message: 'Story rule cleanup failed.'
+    });
   });
 
   test('resolves relative mock replacements from config file location', async () => {
@@ -128,7 +202,6 @@ describe('story rules', () => {
         ]
       }),
       configFilePath,
-      mode: 'development',
       story: {
         id: 'components-card--default'
       }
@@ -150,7 +223,6 @@ describe('story rules', () => {
             }
           ]
         }),
-        mode: 'development',
         story: {
           id: 'components-card--default'
         }
@@ -171,7 +243,6 @@ describe('story rules', () => {
             }
           ]
         }),
-        mode: 'development',
         story: {
           id: 'components-card--default'
         }

package/src/rules.ts

@@ -1,16 +1,11 @@
 import { dirname, isAbsolute, resolve } from 'node:path';
-import type { RequestHandler } from 'msw';
 import type { RenderStoryInput } from './types.ts';
 
-type StoryMode = 'development' | 'production';
-type StoryRuleUseResult = void | Promise<void>;
+export type StoryRuleCleanup = () => void | Promise<void>;
+type StoryRuleUseResult = void | StoryRuleCleanup | Promise<void | StoryRuleCleanup>;
 
 export type StoryRuleUseContext = {
-  mode: StoryMode;
   story: StoryRuleStory;
-  msw: {
-    use: (...handlers: RequestHandler[]) => void;
-  };
   mock: (specifier: string, replacement: string) => void;
 };
 
@@ -35,18 +30,17 @@ export type StoryRuleStory = {
 export type StoryRuleSelectionInput = {
   configModule: unknown;
   configFilePath?: string;
-  mode: StoryMode;
   story?: RenderStoryInput;
 };
 
 export type StoryRuleSelection = {
   moduleMocks: Map<string, string>;
-  mswHandlers: RequestHandler[];
+  cleanups: StoryRuleCleanup[];
 };
 
 type MutableStoryRuleSelection = {
   moduleMocks: Map<string, string>;
-  mswHandlers: RequestHandler[];
+  cleanups: StoryRuleCleanup[];
 };
 
 export function defineStoryRules(config: StoryRulesConfig): StoryRulesConfig {
@@ -72,14 +66,8 @@ export async function selectStoryRules(
         throw new Error('Each story rule "use" entry must be a function.');
       }
 
-      await use({
-        mode: input.mode,
+      const cleanup = await use({
         story,
-        msw: {
-          use: (...handlers) => {
-            selection.mswHandlers.push(...handlers);
-          }
-        },
         mock: (specifier, replacement) => {
           const normalizedSpecifier = normalizeMockSpecifier(specifier);
           const normalizedReplacement = normalizeMockReplacement(replacement, input.configFilePath);
@@ -87,12 +75,73 @@ export async function selectStoryRules(
           selection.moduleMocks.set(normalizedSpecifier, normalizedReplacement);
         }
       });
+
+      if (cleanup !== undefined) {
+        if (typeof cleanup !== 'function') {
+          throw new Error('Story rule "use" must return either nothing or a cleanup function.');
+        }
+
+        selection.cleanups.push(cleanup);
+      }
     }
   }
 
   return selection;
 }
 
+export async function withStoryRuleCleanups<T>(
+  cleanups: StoryRuleCleanup[],
+  callback: () => Promise<T>
+): Promise<T> {
+  let result: T | undefined;
+  let callbackError: unknown;
+
+  try {
+    result = await callback();
+  } catch (error) {
+    callbackError = error;
+  }
+
+  try {
+    await runStoryRuleCleanups(cleanups);
+  } catch (cleanupError) {
+    if (callbackError) {
+      throw new AggregateError(
+        [callbackError, cleanupError],
+        'Story rule execution and cleanup both failed.'
+      );
+    }
+
+    throw cleanupError;
+  }
+
+  if (callbackError) {
+    throw callbackError;
+  }
+
+  return result as T;
+}
+
+export async function runStoryRuleCleanups(cleanups: StoryRuleCleanup[]): Promise<void> {
+  const errors: unknown[] = [];
+
+  for (let index = cleanups.length - 1; index >= 0; index -= 1) {
+    try {
+      await cleanups[index]();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+
+  if (errors.length > 1) {
+    throw new AggregateError(errors, 'Story rule cleanup failed.');
+  }
+}
+
 function normalizeRulesConfig(configModule: unknown): StoryRulesConfig {
   const configExport = getRulesConfigExport(configModule);
 
@@ -293,7 +342,7 @@ function slugify(input: string): string {
 function createEmptySelection(): MutableStoryRuleSelection {
   return {
     moduleMocks: new Map(),
-    mswHandlers: []
+    cleanups: []
   };
 }
 

package/src/server/index.ts

@@ -0,0 +1,111 @@
+import { timingSafeEqual } from 'node:crypto';
+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 {
+  storybookAstroServerAuthHeader,
+  storybookAstroServerAuthToken
+} from 'virtual:storybook-astro-server-auth-config';
+
+const app = new Hono();
+const renderHandlerPromise = createRenderHandler();
+
+app.use(
+  '*',
+  cors({
+    origin: '*',
+    allowMethods: ['GET', 'POST'],
+    allowHeaders: ['Content-Type', storybookAstroServerAuthHeader]
+  })
+);
+
+app.get('/', async (context) => context.text('OK'));
+
+app.post('/render', async (context) => {
+  if (!isRequestAuthorized(context.req.header(storybookAstroServerAuthHeader))) {
+    return context.text('Unauthorized', 401);
+  }
+
+  const input = (await context.req.json()) as Partial<HandlerProps>;
+  const renderHandler = await renderHandlerPromise;
+  const html = await renderHandler({
+    component: input.component ?? '',
+    args: input.args ?? {},
+    slots: input.slots ?? {},
+    story: input.story
+  });
+
+  return context.text(html);
+});
+
+export default app;
+
+async function createRenderHandler() {
+  return handlerFactory([], {
+    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
+      };
+    }
+  });
+}
+
+function isRequestAuthorized(headerValue: string | undefined) {
+  if (!storybookAstroServerAuthToken) {
+    return true;
+  }
+
+  const normalizedHeaderValue = normalizeHeaderValue(headerValue);
+
+  if (!normalizedHeaderValue) {
+    return false;
+  }
+
+  return isSecureEqual(normalizedHeaderValue, storybookAstroServerAuthToken);
+}
+
+function normalizeHeaderValue(value: string | undefined) {
+  if (!value) {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+
+  if (!trimmedValue) {
+    return undefined;
+  }
+
+  if (storybookAstroServerAuthHeader === 'authorization' && trimmedValue.startsWith('Bearer ')) {
+    return trimmedValue.slice('Bearer '.length).trim();
+  }
+
+  return trimmedValue;
+}
+
+function isSecureEqual(actual: string, expected: string) {
+  const actualBuffer = Buffer.from(actual);
+  const expectedBuffer = Buffer.from(expected);
+
+  if (actualBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+
+  return timingSafeEqual(actualBuffer, expectedBuffer);
+}

package/src/testing/renderer-daemon.ts

@@ -1,5 +1,6 @@
 import { createServer as createHttpServer } from 'node:http';
 import type { IncomingMessage } from 'node:http';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { ViteDevServer } from 'vite';
 import { createViteServer } from '../viteStorybookAstroMiddlewarePlugin.ts';
@@ -118,7 +119,15 @@ export async function startTestingRendererDaemon(): Promise<RunningDaemon> {
       renderHandlerPromises.set(resolveFrom, (async () => {
         const integrations = resolveTestingIntegrationsForRoot(resolveFrom);
         const viteServer = await getViteServer(resolveFrom);
-        const middlewareModulePath = fileURLToPath(new URL('../middleware', import.meta.url));
+        // In the workspace this file is src/testing/renderer-daemon.ts so
+        // '../middleware.ts' resolves to src/middleware.ts (Vite handles .ts).
+        // When compiled by tsup, this code lands in a dist/chunk-*.js file so
+        // '../middleware.ts' would resolve to framework/middleware.ts which does
+        // not exist; fall back to './middleware.js' (sibling in dist/).
+        const middlewareSrcPath = fileURLToPath(new URL('../middleware.ts', import.meta.url));
+        const middlewareModulePath = existsSync(middlewareSrcPath)
+          ? middlewareSrcPath
+          : fileURLToPath(new URL('./middleware.js', import.meta.url));
         const middleware = await runWithWorkingDirectory(resolveFrom, () =>
           viteServer.ssrLoadModule(middlewareModulePath, {
             fixStacktrace: true

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;
 }