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

package/src/storySsrVite.ts

@@ -0,0 +1,240 @@
+import { createRequire } from 'node:module';
+import { createServer, mergeConfig, type Plugin, type ViteDevServer } from 'vite';
+import type { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { ensureAstroPassthroughImageService } from './astroImageService.ts';
+import { importAstroConfig } from './importAstroConfig.ts';
+import type { Integration } from './integrations/index.ts';
+import { ssrLoadModuleWithFsFallback } from './lib/ssr-load-module-with-fs-fallback.ts';
+import { resolveStoryModuleMock } from './module-mocks.ts';
+import { vitePluginAstroFontsFallback } from './vitePluginAstroFontsFallback.ts';
+import { vitePluginAstroIntegrationOptsFallback } from './vitePluginAstroIntegrationOptsFallback.ts';
+import { vitePluginAstroRoutesFallback } from './vitePluginAstroRoutesFallback.ts';
+import { vitePluginAstroVueFallback } from './vitePluginAstroVueFallback.ts';
+import { vitePluginStoryModuleMocks } from './vitePluginStoryModuleMocks.ts';
+
+export async function createStorySsrViteServer(options: {
+  integrations: Integration[];
+  trackedSpecifiers: Set<string>;
+  resolveFrom: string;
+}) {
+  const { getViteConfig, passthroughImageService } = await importAstroConfig(options.resolveFrom);
+  const astroConfig = await getViteConfig(
+    { root: options.resolveFrom },
+    {
+      configFile: false,
+      integrations: await Promise.all(
+        options.integrations.map((integration) => integration.loadIntegration(options.resolveFrom))
+      ),
+      image: { service: passthroughImageService() }
+    }
+  )({
+    mode: 'production',
+    command: 'serve'
+  });
+
+  const config = mergeConfig(astroConfig, {
+    appType: 'custom',
+    server: {
+      middlewareMode: true
+    },
+    ssr: {
+      // Keep Astro runtime classes in the Vite SSR graph so containers and
+      // components share SlotString/HTMLString instances during prerendering.
+      noExternal: /^astro(\/.+)?$/
+    },
+    plugins: [
+      createProjectAstroResolutionPlugin(options.resolveFrom),
+      vitePluginAstroFontsFallback(),
+      vitePluginAstroIntegrationOptsFallback(),
+      vitePluginAstroVueFallback(),
+      vitePluginAstroRoutesFallback(),
+      vitePluginStoryModuleMocks(),
+      createTrackedSpecifierStubPlugin(options.trackedSpecifiers)
+    ]
+  });
+
+  const viteServer = await createServer(config);
+
+  await viteServer.pluginContainer.buildStart({});
+
+  return viteServer;
+}
+
+export async function loadRulesConfigModule(viteServer: ViteDevServer, configFilePath?: string) {
+  if (!configFilePath) {
+    return undefined;
+  }
+
+  try {
+    return await ssrLoadModuleWithFsFallback(viteServer, configFilePath, {
+      fixStacktrace: true
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+
+    throw new Error(
+      `Unable to load framework.options.storyRules config module at ${configFilePath}: ${reason}`
+    );
+  }
+}
+
+export function createClientModuleResolver(
+  integrations: Integration[],
+  staticModuleMap: Record<string, string>
+) {
+  return function resolveClientModule(specifier: string) {
+    if (Object.hasOwn(staticModuleMap, specifier)) {
+      return staticModuleMap[specifier];
+    }
+
+    const normalizedSpecifier = specifier.replace(/\\/g, '/').replace(/\?.*$/, '');
+
+    if (Object.hasOwn(staticModuleMap, normalizedSpecifier)) {
+      return staticModuleMap[normalizedSpecifier];
+    }
+
+    for (const integration of integrations) {
+      const resolution = integration.resolveClient(specifier);
+
+      if (resolution) {
+        return resolution;
+      }
+    }
+  };
+}
+
+export async function createProductionAstroContainer(options: {
+  integrations: Integration[];
+  resolveClientModule: (specifier: string) => string | undefined;
+  viteServer: ViteDevServer;
+}) {
+  ensureAstroPassthroughImageService();
+
+  // Astro 6's container wraps each slot value in a SlotString, and the
+  // rendering pipeline detects raw-HTML slot chunks via `instanceof SlotString`.
+  // If the container is loaded by Node's ESM resolver while components are
+  // loaded through Vite's SSR graph, the two paths produce different
+  // SlotString classes and the instanceof check fails — slot content then
+  // takes the escaping code path. Loading the container via the same Vite
+  // SSR server keeps the class identity consistent.
+  const containerModule = (await options.viteServer.ssrLoadModule('astro/container')) as {
+    experimental_AstroContainer: typeof AstroContainer;
+  };
+  const ViteAstroContainer = containerModule.experimental_AstroContainer;
+
+  const container = await ViteAstroContainer.create({
+    resolve: async (specifier) => {
+      const mockedModule = resolveStoryModuleMock(specifier);
+
+      if (mockedModule) {
+        return mockedModule;
+      }
+
+      const resolution = options.resolveClientModule(specifier);
+
+      if (resolution) {
+        return resolution;
+      }
+
+      return specifier;
+    }
+  });
+
+  await addContainerRenderers(
+    container,
+    options.integrations,
+    options.resolveClientModule,
+    options.viteServer
+  );
+
+  return container;
+}
+
+export async function addContainerRenderers(
+  container: Awaited<ReturnType<typeof AstroContainer.create>>,
+  integrations: Integration[],
+  resolveClientModule: (specifier: string) => string | undefined,
+  viteServer: ViteDevServer
+) {
+  for (const integration of integrations) {
+    const serverRenderer = integration.renderer.server;
+
+    if (serverRenderer) {
+      const serverRendererModule = await viteServer.ssrLoadModule(serverRenderer.entrypoint);
+      const renderer = serverRendererModule.default ?? serverRendererModule;
+
+      if (integration.name === 'solid' && isRecord(renderer)) {
+        container.addServerRenderer({
+          name: serverRenderer.name,
+          renderer: {
+            ...renderer,
+            name: serverRenderer.name
+          } as never
+        });
+      } else {
+        container.addServerRenderer({
+          name: serverRenderer.name,
+          renderer
+        });
+      }
+    }
+
+    const clientRenderer = integration.renderer.client;
+
+    if (clientRenderer) {
+      const resolvedEntrypoint =
+        resolveClientModule(clientRenderer.entrypoint) ?? clientRenderer.entrypoint;
+
+      container.addClientRenderer({
+        name: clientRenderer.name,
+        entrypoint: resolvedEntrypoint
+      });
+    }
+  }
+}
+
+function createProjectAstroResolutionPlugin(resolveFrom: string): Plugin {
+  const require = createRequire(import.meta.url);
+
+  return {
+    name: 'storybook-astro:resolve-project-astro-shared',
+    enforce: 'pre',
+    resolveId(id: string) {
+      if (id !== 'astro' && !id.startsWith('astro/')) {
+        return null;
+      }
+
+      try {
+        return require.resolve(id, {
+          paths: [resolveFrom]
+        });
+      } catch {
+        return null;
+      }
+    }
+  } satisfies Plugin;
+}
+
+function createTrackedSpecifierStubPlugin(trackedSpecifiers: Set<string>): Plugin {
+  return {
+    name: 'storybook-astro:shared-ssr-stubs',
+    resolveId(id: string) {
+      if (trackedSpecifiers.has(id)) {
+        return `\0storybook-astro-shared-ssr-stub:${encodeURIComponent(id)}`;
+      }
+
+      return null;
+    },
+    load(id: string) {
+      if (id.startsWith('\0storybook-astro-shared-ssr-stub:')) {
+        return 'export default undefined;';
+      }
+
+      return null;
+    }
+  } satisfies Plugin;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/types.ts

@@ -37,15 +37,6 @@ type StaticFrameworkOptions = BaseFrameworkOptions & {
   renderMode: 'static';
   storyRules?: StoryRulesOptions;
   server?: never;
-  /**
-   * Additional source directories (relative to `resolveFrom`) to scan for
-   * hydratable client components (JSX/TSX/Vue/Svelte). Use this when stories
-   * reference components that live outside the default `src/components` scan
-   * root — for example, workspace packages included in the `stories` globs.
-   *
-   * @example ['../../packages/components/src']
-   */
-  componentRoots?: string[];
 };
 
 export type FrameworkOptions = ServerFrameworkOptions | StaticFrameworkOptions;

package/src/virtual.d.ts

@@ -22,7 +22,7 @@ declare module 'virtual:storybook-astro-renderer' {
   export function applyStyles(): void;
 }
 
-declare module 'virtual:storybook-astro-sanitization-config' {
+declare module 'virtual:storybook-astro/sanitize-config' {
   import type { SanitizationOptions } from './lib/sanitization.ts';
 
   const sanitization: SanitizationOptions | undefined;
@@ -30,16 +30,30 @@ declare module 'virtual:storybook-astro-sanitization-config' {
   export default sanitization;
 }
 
-declare module 'virtual:storybook-astro-story-rules-config' {
+declare module 'virtual:storybook-astro/story-rules' {
   const configModule: unknown;
 
   export default configModule;
   export const storybookAstroStoryRulesConfigFilePath: string | undefined;
 }
 
-declare module 'virtual:storybook-astro-server-auth-config' {
+declare module 'virtual:storybook-astro/server-auth' {
   export const storybookAstroServerAuthToken: string | undefined;
   export const storybookAstroServerAuthHeader: string;
 }
 
+declare module 'virtual:storybook-astro/server-runtime' {
+  import type { Integration } from './integrations/index.ts';
+
+  export const runtimeConfig: {
+    snapshotDirName: string;
+    storyRulesConfigRelativePath: string | undefined;
+    componentPathMap: Record<string, string>;
+    staticModuleMap: Record<string, string>;
+    staticCssMap: Record<string, string[]>;
+    trackedSpecifiers: string[];
+  };
+  export const integrations: Integration[];
+}
+
 declare module 'virtual:storybook-renderer-fallback' {}

package/src/vite/{astroFilesVirtualModulePlugin.ts → astroFilesPlugin.ts}

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+import { createVirtualModule } from './virtualModulePlugin.ts';
 
 type ImportRecord = {
   id: string;
@@ -7,9 +7,9 @@ type ImportRecord = {
   importStatement: string;
 };
 
-export function astroFilesVirtualModulePlugin(astroComponents: string[]): Plugin {
-  return createVirtualModulePlugin({
-    pluginName: 'storybook-astro:virtual-astro-files',
+export function astroFilesPlugin(astroComponents: string[]): Plugin {
+  return createVirtualModule({
+    pluginName: 'storybook-astro:astro-files',
     virtualModuleId: 'virtual:astro-files',
     load() {
       const imports = astroComponents.reduce<ImportRecord[]>((records, file, index) => {

package/src/vite/sanitizeConfigPlugin.ts

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

package/src/vite/{storybookAstroServerAuthConfigVirtualModulePlugin.test.ts → serverAuthPlugin.test.ts}

@@ -1,9 +1,6 @@
 import type { PluginOption } from 'vite';
 import { describe, expect, test } from 'vitest';
-import {
-  STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID,
-  storybookAstroServerAuthConfigVirtualModulePlugin
-} from './storybookAstroServerAuthConfigVirtualModulePlugin.ts';
+import { SERVER_AUTH_MODULE_ID, serverAuthPlugin } from './serverAuthPlugin.ts';
 
 function getPlugin(pluginOption: PluginOption) {
   if (Array.isArray(pluginOption)) {
@@ -34,19 +31,19 @@ function getHookHandler<T extends (...args: unknown[]) => unknown>(hook: unknown
   throw new Error('Expected hook to be a function or an object with a handler function.');
 }
 
-describe('storybookAstroServerAuthConfigVirtualModulePlugin', () => {
+describe('serverAuthPlugin', () => {
   test('normalizes auth token and header values', async () => {
     const plugin = getPlugin(
-      storybookAstroServerAuthConfigVirtualModulePlugin({
+      serverAuthPlugin({
         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);
+    const resolvedId = resolveId(SERVER_AUTH_MODULE_ID);
 
-    expect(resolvedId).toBe(`\0${STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID}`);
+    expect(resolvedId).toBe(`\0${SERVER_AUTH_MODULE_ID}`);
     await expect(load(resolvedId!)).resolves.toBe(
       'export const storybookAstroServerAuthToken = "test-token";\n' +
         'export const storybookAstroServerAuthHeader = "x-storybook-token";'
@@ -55,14 +52,14 @@ describe('storybookAstroServerAuthConfigVirtualModulePlugin', () => {
 
   test('falls back to authorization header and undefined token', async () => {
     const plugin = getPlugin(
-      storybookAstroServerAuthConfigVirtualModulePlugin({
+      serverAuthPlugin({
         authToken: '   '
       })
     );
     const load = getHookHandler<(id: string) => Promise<string | undefined>>(plugin.load);
 
     await expect(
-      load(`\0${STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID}`)
+      load(`\0${SERVER_AUTH_MODULE_ID}`)
     ).resolves.toBe(
       'export const storybookAstroServerAuthToken = undefined;\n' +
         'export const storybookAstroServerAuthHeader = "authorization";'

package/src/vite/{storybookAstroServerAuthConfigVirtualModulePlugin.ts → serverAuthPlugin.ts}

@@ -1,19 +1,16 @@
 import type { Plugin } from 'vite';
 import type { ServerBuildOptions } from '../types.ts';
-import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+import { createVirtualModule } from './virtualModulePlugin.ts';
 
-export const STORYBOOK_ASTRO_SERVER_AUTH_CONFIG_VIRTUAL_MODULE_ID =
-  'virtual:storybook-astro-server-auth-config';
+export const SERVER_AUTH_MODULE_ID = 'virtual:storybook-astro/server-auth';
 
-export function storybookAstroServerAuthConfigVirtualModulePlugin(
-  options?: ServerBuildOptions
-): Plugin {
+export function serverAuthPlugin(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,
+  return createVirtualModule({
+    pluginName: 'storybook-astro:server-auth',
+    virtualModuleId: SERVER_AUTH_MODULE_ID,
     load() {
       return [
         `export const storybookAstroServerAuthToken = ${

package/src/vite/serverRuntimePlugin.ts

@@ -0,0 +1,109 @@
+import { relative } from 'node:path';
+import type { Integration } from '../integrations/index.ts';
+import { resolveRulesConfigFilePath } from '../rules-options.ts';
+import type { FrameworkOptions } from '../types.ts';
+import { createVirtualModule } from './virtualModulePlugin.ts';
+
+export const SERVER_RUNTIME_MODULE_ID = 'virtual:storybook-astro/server-runtime';
+const integrationsModuleId = '@storybook-astro/framework/integrations';
+
+function getIntegrationFactoryName(integration: Integration): string {
+  return integration.factoryName ?? integration.name;
+}
+
+/** Produces the virtual module that hands the standalone render server its build-time config. */
+export function serverRuntimePlugin(options: {
+  integrations?: FrameworkOptions['integrations'];
+  storyRules?: FrameworkOptions['storyRules'];
+  resolveFrom: string;
+  snapshotDirName: string;
+  componentPathMap: Record<string, string>;
+  staticModuleMap: Record<string, string>;
+  staticCssMap: Record<string, string[]>;
+  trackedSpecifiers: string[];
+}) {
+  return createVirtualModule({
+    pluginName: 'storybook-astro:server-runtime',
+    virtualModuleId: SERVER_RUNTIME_MODULE_ID,
+    load() {
+      const storyRulesConfigFilePath = resolveRulesConfigFilePath(options.storyRules, options.resolveFrom);
+      const storyRulesConfigRelativePath = storyRulesConfigFilePath
+        ? relative(options.resolveFrom, storyRulesConfigFilePath).replace(/\\/g, '/')
+        : undefined;
+      const integrations = options.integrations ?? [];
+      // Keep the generated module small: one config object for plain data,
+      // one integrations export for real factory calls.
+      const runtimeConfig = {
+        snapshotDirName: options.snapshotDirName,
+        storyRulesConfigRelativePath,
+        componentPathMap: options.componentPathMap,
+        staticModuleMap: options.staticModuleMap,
+        staticCssMap: options.staticCssMap,
+        trackedSpecifiers: options.trackedSpecifiers
+      };
+
+      return [
+        createIntegrationImports(integrations),
+        `export const runtimeConfig = ${serializeValue(runtimeConfig)};`,
+        `export const integrations = [${createIntegrationFactoryCalls(integrations)}];`
+      ].join('\n');
+    }
+  });
+}
+
+/** Imports only the integration factories used by this runtime bundle. */
+function createIntegrationImports(integrations: Integration[]) {
+  const factoryNames = Array.from(new Set(integrations.map(getIntegrationFactoryName)));
+
+  if (factoryNames.length === 0) {
+    return '';
+  }
+
+  return `import { ${factoryNames.join(', ')} } from ${JSON.stringify(integrationsModuleId)};`;
+}
+
+/** Recreates the configured integration list inside the generated runtime module. */
+function createIntegrationFactoryCalls(integrations: Integration[]) {
+  return integrations
+    .map((integration) => `${getIntegrationFactoryName(integration)}(${serializeValue(integration.options)})`)
+    .join(', ');
+}
+
+/** Serializes plain runtime config values into executable module source. */
+function serializeValue(value: unknown): string {
+  if (value === undefined) {
+    return 'undefined';
+  }
+
+  if (value === null) {
+    return 'null';
+  }
+
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return JSON.stringify(value);
+  }
+
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => serializeValue(entry)).join(', ')}]`;
+  }
+
+  if (isRecord(value)) {
+    return `{${Object.entries(value)
+      .map(([key, entryValue]) => `${JSON.stringify(key)}: ${serializeValue(entryValue)}`)
+      .join(', ')}}`;
+  }
+
+  throw new Error('Unable to serialize Storybook Astro server runtime configuration.');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/vite/{storybookAstroRulesConfigVirtualModulePlugin.ts → storyRulesPlugin.ts}

@@ -1,18 +1,17 @@
 import type { Plugin } from 'vite';
 import type { StoryRulesOptions } from '../rules-options.ts';
 import { resolveRulesConfigFilePath } from '../rules-options.ts';
-import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+import { createVirtualModule } from './virtualModulePlugin.ts';
 
-export const STORYBOOK_ASTRO_STORY_RULES_CONFIG_VIRTUAL_MODULE_ID =
-  'virtual:storybook-astro-story-rules-config';
+export const STORY_RULES_MODULE_ID = 'virtual:storybook-astro/story-rules';
 
-export function storybookAstroStoryRulesConfigVirtualModulePlugin(
+export function storyRulesPlugin(
   options?: StoryRulesOptions,
   resolveFrom = process.cwd()
 ): Plugin {
-  return createVirtualModulePlugin({
-    pluginName: 'storybook-astro:virtual-story-rules-config',
-    virtualModuleId: STORYBOOK_ASTRO_STORY_RULES_CONFIG_VIRTUAL_MODULE_ID,
+  return createVirtualModule({
+    pluginName: 'storybook-astro:story-rules',
+    virtualModuleId: STORY_RULES_MODULE_ID,
     load() {
       const configFilePath = resolveRulesConfigFilePath(options, resolveFrom);
 

package/src/vite/{createVirtualModulePlugin.test.ts → virtualModulePlugin.test.ts}

@@ -1,6 +1,6 @@
 import type { PluginOption } from 'vite';
 import { describe, expect, test, vi } from 'vitest';
-import { createVirtualModulePlugin } from './createVirtualModulePlugin.ts';
+import { createVirtualModule } from './virtualModulePlugin.ts';
 
 function getPlugin(pluginOption: PluginOption) {
   if (Array.isArray(pluginOption)) {
@@ -31,9 +31,9 @@ function getHookHandler<T extends (...args: unknown[]) => unknown>(hook: unknown
   throw new Error('Expected hook to be a function or an object with a handler function.');
 }
 
-describe('createVirtualModulePlugin', () => {
+describe('createVirtualModule', () => {
   test('resolves configured virtual module id with a null-byte prefix', () => {
-    const pluginOption = createVirtualModulePlugin({
+    const pluginOption = createVirtualModule({
       pluginName: 'test:virtual-module',
       virtualModuleId: 'virtual:test-module',
       load: () => 'export default true;'
@@ -48,7 +48,7 @@ describe('createVirtualModulePlugin', () => {
 
   test('loads module content only for the resolved virtual module id', async () => {
     const load = vi.fn(() => 'export const message = "hello";');
-    const pluginOption = createVirtualModulePlugin({
+    const pluginOption = createVirtualModule({
       pluginName: 'test:virtual-module',
       virtualModuleId: 'virtual:test-module',
       load
@@ -67,7 +67,7 @@ describe('createVirtualModulePlugin', () => {
   });
 
   test('supports asynchronous virtual module loaders', async () => {
-    const pluginOption = createVirtualModulePlugin({
+    const pluginOption = createVirtualModule({
       pluginName: 'test:virtual-module',
       virtualModuleId: 'virtual:test-module',
       load: async () => 'export default "async";'

package/src/vite/{createVirtualModulePlugin.ts → virtualModulePlugin.ts}

@@ -1,12 +1,12 @@
 import type { Plugin } from 'vite';
 
-type CreateVirtualModulePluginOptions = {
+type CreateVirtualModuleOptions = {
   pluginName: string;
   virtualModuleId: string;
   load: (id: string) => string | Promise<string> | undefined;
 };
 
-export function createVirtualModulePlugin(options: CreateVirtualModulePluginOptions): Plugin {
+export function createVirtualModule(options: CreateVirtualModuleOptions): Plugin {
   const resolvedVirtualModuleId = `\0${options.virtualModuleId}`;
 
   return {