@poveste/plugin-nuxt 0.6.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Guillaume Chau (original "histoire" project)
+Copyright (c) 2026 Sorin Gitlan (poveste fork)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -7,4 +7,6 @@ export interface HstNuxtOptions {
      */
     excludePlugins?: (string | RegExp)[];
 }
+export declare function isPluginExcluded(src: string, patterns: (string | RegExp)[]): boolean;
+export declare function wrapPluginsForTolerantBoot(source: string): string;
 export declare function HstNuxt(options?: HstNuxtOptions): Plugin;

package/dist/index.js

@@ -10,10 +10,30 @@ const ignorePlugins = [
     'nuxt:import-protection',
 ];
 // Some Nuxt modules register client plugins that assume a full Nuxt runtime the
-// headless story sandbox can't provide, so they 500 the iframe on entry boot;
-// @nuxtjs/i18n's are dropped by default (#65), and `excludePlugins` drops more
-// without patching this package (#277).
+// headless story sandbox can't provide. The general net is `wrapPluginsForTolerantBoot`
+// below, which skips one that throws rather than 500-ing the iframe; this list drops
+// known offenders before they run at all — @nuxtjs/i18n by default (#65), plus whatever
+// `excludePlugins` adds (#277), which is also the only lever for a plugin that throws at
+// import, before the tolerant wrapper can catch it.
 const DEFAULT_EXCLUDED_PLUGINS = [/[\\/]@nuxtjs[\\/]i18n[\\/].*[\\/]plugins[\\/]/];
+// Whether a resolved plugin `src` matches any exclusion pattern. `match`, not
+// `test`: it doesn't advance a caller's /g regex `lastIndex`, so matching stays
+// stateless without mutating an input we don't own.
+export function isPluginExcluded(src, patterns) {
+    return patterns.some(pattern => typeof pattern === 'string' ? src.includes(pattern) : src.match(pattern) !== null);
+}
+// Wrap Nuxt's generated client-plugin list so each plugin boots tolerantly
+// (#277): map the exported array through `__povesteTolerant`. Reuses Nuxt's own
+// ordering by transforming its output rather than reimplementing it. Returns the
+// source untouched if the `export default [...]` shape is not found, so an
+// upstream format change degrades to today's behaviour instead of breaking.
+export function wrapPluginsForTolerantBoot(source) {
+    const wrapped = source.replace(/export default (\[[\s\S]*?\])/, 'export default $1.map(__povesteTolerant)');
+    if (wrapped === source) {
+        return source;
+    }
+    return `import { __povesteTolerant } from '#build/poveste/tolerant-plugins.mjs'\n${wrapped}`;
+}
 export function HstNuxt(options = {}) {
     let nuxt;
     return {
@@ -132,20 +152,29 @@ async function useNuxtViteConfig(excludePlugins) {
         throw new Error(`Poveste only supports Vite bundler, but Nuxt builder is currently set to '${nuxt.options.builder}'.`);
     }
     const runtimeDir = fileURLToPath(new URL('../runtime', import.meta.url));
-    nuxt.options.build.templates.push({ src: join(runtimeDir, 'composables.mjs'), filename: 'poveste/composables.mjs' }, { src: join(runtimeDir, 'components.mjs'), filename: 'poveste/components.mjs' });
+    nuxt.options.build.templates.push({ src: join(runtimeDir, 'composables.mjs'), filename: 'poveste/composables.mjs' }, { src: join(runtimeDir, 'components.mjs'), filename: 'poveste/components.mjs' }, { src: join(runtimeDir, 'tolerant-plugins.mjs'), filename: 'poveste/tolerant-plugins.mjs' });
     // Drop the sandbox-incompatible client plugins named by `excludePlugins`, so
     // they don't 500 the story iframe on entry boot. See DEFAULT_EXCLUDED_PLUGINS.
     nuxt.hook('app:resolve', (app) => {
-        app.plugins = app.plugins.filter((p) => {
-            const src = p.src ?? '';
-            // `match`, not `test`: it doesn't advance a caller's /g regex `lastIndex`, so
-            // matching stays stateless without mutating an input we don't own.
-            return !excludePlugins.some(pattern => typeof pattern === 'string' ? src.includes(pattern) : src.match(pattern) !== null);
-        });
+        app.plugins = app.plugins.filter(p => !isPluginExcluded(p.src ?? '', excludePlugins));
     });
     nuxt.hook('app:templates', (app) => {
         app.templates = app.templates.filter(template => template.filename !== 'app-component.mjs');
         app.templates.push({ src: join(runtimeDir, 'app-component.mjs'), filename: 'app-component.mjs' });
+        // Tolerant boot (#277): wrap each generated client plugin so one that throws
+        // while setting up in the sandbox is logged and skipped, not fatal to the
+        // whole iframe. `excludePlugins` drops what we know can't run; this catches
+        // the rest.
+        for (const template of app.templates) {
+            if (template.filename !== 'plugins.client.mjs' && template.filename !== 'plugins.server.mjs') {
+                continue;
+            }
+            const original = template.getContents;
+            if (!original) {
+                continue;
+            }
+            template.getContents = async (ctx) => wrapPluginsForTolerantBoot(await original(ctx));
+        }
     });
     nuxt.hook('imports:sources', (presets) => {
         const polyfills = ['requestIdleCallback', 'cancelIdleCallback'];

package/package.json

@@ -1,17 +1,35 @@
 {
   "name": "@poveste/plugin-nuxt",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Poveste plugin to integrate with Nuxt 4",
   "author": {
     "name": "Sorin Gitlan"
   },
   "license": "MIT",
+  "homepage": "https://poveste.dev",
   "repository": {
     "url": "https://github.com/poveste-dev/poveste.git",
     "type": "git",
     "directory": "packages/poveste-plugin-nuxt"
   },
+  "bugs": "https://github.com/poveste-dev/poveste/issues",
+  "keywords": [
+    "poveste",
+    "histoire",
+    "storybook",
+    "component-playground",
+    "component-explorer",
+    "stories",
+    "styleguide",
+    "design-system",
+    "vite",
+    "nuxt",
+    "nuxt4",
+    "vue",
+    "plugin",
+    "module"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -22,14 +40,17 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "scripts": {
-    "build": "rimraf dist && tsc -d",
-    "watch": "tsc -d -w --sourceMap"
+  "files": [
+    "dist",
+    "runtime"
+  ],
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "peerDependencies": {
-    "@poveste/plugin-vue": "workspace:^",
     "nuxt": "^4.5.0",
-    "poveste": "workspace:^"
+    "poveste": "^0.7.0",
+    "@poveste/plugin-vue": "^0.7.0"
   },
   "dependencies": {
     "@nuxt/kit": "^4.5.2",
@@ -41,8 +62,14 @@
   "devDependencies": {
     "@nuxt/schema": "^4.5.2",
     "@types/node": "^22.10.1",
-    "poveste": "workspace:*",
-    "typescript": "catalog:",
-    "vite": "catalog:"
+    "typescript": "5.6.3",
+    "vite": "^8.2.0",
+    "vitest": "^4.1.10",
+    "poveste": "0.7.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -d",
+    "watch": "tsc -d -w --sourceMap",
+    "test": "vitest run"
   }
-}
+}

package/runtime/tolerant-plugins.mjs

@@ -0,0 +1,28 @@
+// Wrap a resolved Nuxt client plugin so a throw while it sets up in the headless
+// story sandbox is logged and skipped, instead of aborting the rest of the boot
+// and painting an error into the iframe (#277). Nuxt's `applyPlugins` stops at
+// the first plugin that throws, so without this one sandbox-hostile module takes
+// down every plugin after it. Metadata (`_name`, `order`, `dependsOn`, ...) is
+// copied over so ordering and dependency resolution are unchanged.
+//
+// This catches setup-time failures only. A plugin that throws at module import
+// fails before this runs — drop those with HstNuxt({ excludePlugins }).
+export function __povesteTolerant(plugin) {
+  if (typeof plugin !== 'function') {
+    return plugin
+  }
+  const wrapped = async (nuxtApp) => {
+    try {
+      return await plugin(nuxtApp)
+    }
+    catch (error) {
+      console.warn(
+        `[poveste] Nuxt client plugin ${plugin._name ?? plugin.name ?? '(anonymous)'} `
+        + 'threw while setting up in the story sandbox; skipping it. Drop it with '
+        + 'HstNuxt({ excludePlugins }) if it can never run headless.',
+        error,
+      )
+    }
+  }
+  return Object.assign(wrapped, plugin)
+}

package/src/global.d.ts

@@ -1,5 +0,0 @@
-declare global {
-  const __HST_COLLECT__: boolean
-}
-
-export {}

package/src/index.ts

@@ -1,230 +0,0 @@
-import type { Nuxt } from '@nuxt/schema'
-import type { Plugin } from 'poveste'
-import type { UserConfig as ViteConfig } from 'vite'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import replace from '@rollup/plugin-replace'
-
-const ignorePlugins = [
-  'nuxt:vite-node-server',
-  'nuxt:dev-style-ssr',
-  'nuxt:vite-relative-asset',
-  'nuxt:cache-dir',
-  'nuxt:dynamic-base-path',
-  'nuxt:import-protection',
-]
-
-export interface HstNuxtOptions {
-  /**
-   * Client plugins to drop from the story sandbox, matched against each
-   * plugin's resolved `src` (string `includes` or `RegExp`). Added on top of
-   * the built-in defaults, not replacing them.
-   */
-  excludePlugins?: (string | RegExp)[]
-}
-
-// Some Nuxt modules register client plugins that assume a full Nuxt runtime the
-// headless story sandbox can't provide, so they 500 the iframe on entry boot;
-// @nuxtjs/i18n's are dropped by default (#65), and `excludePlugins` drops more
-// without patching this package (#277).
-const DEFAULT_EXCLUDED_PLUGINS: (string | RegExp)[] = [/[\\/]@nuxtjs[\\/]i18n[\\/].*[\\/]plugins[\\/]/]
-
-export function HstNuxt(options: HstNuxtOptions = {}): Plugin {
-  let nuxt: Nuxt
-  return {
-    name: '@poveste/plugin-nuxt',
-
-    async defaultConfig() {
-      const nuxtViteConfig = await useNuxtViteConfig([...DEFAULT_EXCLUDED_PLUGINS, ...(options.excludePlugins ?? [])])
-      const { viteConfig } = nuxtViteConfig
-
-      nuxt = nuxtViteConfig.nuxt // We save it to close it later
-      const plugins = viteConfig.plugins.filter((p: any) => !ignorePlugins.includes(p?.name))
-      return {
-        vite: {
-          server: {
-            watch: viteConfig.server.watch,
-            fs: {
-              allow: viteConfig.server.fs.allow,
-            },
-            middlewareMode: false,
-          },
-          define: {
-            ...viteConfig.define,
-            'process.server': false,
-            'process.client': true,
-            'process.browser': true,
-            'process.nitro': false,
-            'process.prerender': false,
-          },
-          resolve: {
-            alias: viteConfig.resolve.alias,
-            extensions: viteConfig.resolve.extensions,
-            dedupe: viteConfig.resolve.dedupe,
-          },
-          plugins: [
-            ...plugins,
-            replace({
-              values: {
-                'import.meta.server': 'false',
-                'import.meta.client': 'true',
-              },
-              preventAssignment: true,
-            }),
-          ],
-          css: viteConfig.css,
-          publicDir: viteConfig.publicDir,
-          optimizeDeps: {
-            ...viteConfig.optimizeDeps,
-            exclude: [
-              ...viteConfig.optimizeDeps.exclude,
-              '@poveste/plugin-nuxt',
-            ],
-          },
-          // @ts-expect-error Vue-specific config
-          vue: viteConfig.vue,
-          logLevel: 'info',
-        },
-        setupCode: [
-          `${nuxt.options.css.map(file => `import '${file}'`).join('\n')}`,
-          `import { setupNuxtApp } from '@poveste/plugin-nuxt/dist/runtime/app-setup.js'
-export async function setupVue3 () {
-  await setupNuxtApp(${JSON.stringify(nuxt.options.runtimeConfig.public)})
-}`,
-        ],
-        viteNodeInlineDeps: [
-          /\/(nuxt|nuxt3)\//,
-          /^#/,
-          /\.nuxt/,
-          ...(nuxt.options.build.transpile.filter(
-            r => typeof r === 'string' || r instanceof RegExp,
-          ) as Array<string | RegExp>),
-        ],
-        build: {
-          excludeFromVendorsChunk: [
-            /nuxt\/dist\/app/,
-          ],
-        },
-      }
-    },
-
-    onDev(api, onCleanup) {
-      onCleanup(async () => {
-        nuxt?.close()
-      })
-    },
-
-    onBuild(api) {
-      api.onBuildEnd(() => {
-        nuxt?.close()
-      })
-    },
-
-    onPreview() {
-      nuxt?.close()
-    },
-  }
-}
-
-async function useNuxtViteConfig(excludePlugins: (string | RegExp)[]) {
-  const { loadNuxt, buildNuxt } = await import('@nuxt/kit')
-  const nuxt = await loadNuxt({
-    // cwd: process.cwd(),
-    ready: false,
-    dev: true,
-    overrides: {
-      // Keep the auxiliary instance out of the host's `.nuxt`: it regenerates
-      // `imports.d.ts` and friends, which any later type-aware lint or vue-tsc
-      // run would then read instead of the application's own (#223).
-      buildDir: '.nuxt/poveste',
-      devtools: { enabled: false },
-      ssr: false,
-      experimental: {
-        appManifest: false,
-      },
-      app: {
-        rootId: 'nuxt-test',
-      },
-      pages: false,
-      typescript: {
-        typeCheck: false,
-      },
-    },
-  })
-  if (nuxt.options.builder as string !== '@nuxt/vite-builder') {
-    throw new Error(`Poveste only supports Vite bundler, but Nuxt builder is currently set to '${nuxt.options.builder}'.`)
-  }
-  const runtimeDir = fileURLToPath(new URL('../runtime', import.meta.url))
-  nuxt.options.build.templates.push(
-    { src: join(runtimeDir, 'composables.mjs'), filename: 'poveste/composables.mjs' },
-    { src: join(runtimeDir, 'components.mjs'), filename: 'poveste/components.mjs' },
-  )
-
-  // Drop the sandbox-incompatible client plugins named by `excludePlugins`, so
-  // they don't 500 the story iframe on entry boot. See DEFAULT_EXCLUDED_PLUGINS.
-  nuxt.hook('app:resolve', (app) => {
-    app.plugins = app.plugins.filter((p) => {
-      const src = p.src ?? ''
-      // `match`, not `test`: it doesn't advance a caller's /g regex `lastIndex`, so
-      // matching stays stateless without mutating an input we don't own.
-      return !excludePlugins.some(pattern =>
-        typeof pattern === 'string' ? src.includes(pattern) : src.match(pattern) !== null)
-    })
-  })
-
-  nuxt.hook('app:templates', (app) => {
-    app.templates = app.templates.filter(template => template.filename !== 'app-component.mjs')
-    app.templates.push({ src: join(runtimeDir, 'app-component.mjs'), filename: 'app-component.mjs' })
-  })
-
-  nuxt.hook('imports:sources', (presets) => {
-    const polyfills = ['requestIdleCallback', 'cancelIdleCallback']
-    const stubbedComposables = ['useNuxtApp']
-    for (const appPreset of presets.filter(p => p && typeof p === 'object' && 'from' in p && p.from?.startsWith('#app'))) {
-      if ('imports' in appPreset && Array.isArray(appPreset.imports)) {
-        appPreset.imports = appPreset.imports.filter(i => typeof i !== 'string' || (!stubbedComposables.includes(i) && !polyfills.includes(i)))
-      }
-    }
-    presets.push({
-      from: '#build/poveste/composables.mjs',
-      imports: stubbedComposables,
-    })
-  })
-
-  return {
-    viteConfig: await new Promise<ViteConfig>((resolve, reject) => {
-      nuxt.hook('modules:done', () => {
-        nuxt.hook('components:extend', (components) => {
-          for (const name of ['NuxtLink']) {
-            Object.assign(components.find(c => c.pascalName === name) || {}, {
-              export: name,
-              filePath: '#build/poveste/components.mjs',
-            })
-          }
-        })
-
-        nuxt.hook('vite:configResolved', (config, { isClient }) => {
-          if (isClient) {
-            resolve(config as any)
-            // The resolved config is all this instance is for. Left running,
-            // `buildNuxt` goes on to build the Nuxt client, start Nitro and
-            // open Nuxt's own dev server — seconds of work on every `poveste
-            // dev` and `poveste build`, a `NUXT_B7005` warning for the entry
-            // it does not have, and an HMR socket on 24678 that collides with
-            // any other Nuxt dev server on the machine (#220, #221). The catch
-            // below has always known this sentinel; nothing threw it.
-            throw new Error('_stop_')
-          }
-        })
-      })
-      nuxt.ready()
-        .then(() => buildNuxt(nuxt))
-        .catch((err) => {
-          if (!err.toString().includes('_stop_')) {
-            reject(err)
-          }
-        })
-    }),
-    nuxt,
-  }
-}

package/src/runtime/app-setup.ts

@@ -1,72 +0,0 @@
-import type { PublicRuntimeConfig } from '@nuxt/schema'
-import type { App } from 'h3'
-import { createApp } from 'h3'
-import { createFetch } from 'ofetch'
-
-export async function setupNuxtApp(publicConfig: PublicRuntimeConfig) {
-  const win = window as unknown as Window & {
-    __app: App
-    __registry: Set<string>
-    __NUXT__: any
-    $fetch: any
-    fetch: any
-    IntersectionObserver: any
-    Headers: any
-  }
-
-  win.__NUXT__ = {
-    serverRendered: false,
-    config: {
-      public: { ...publicConfig },
-      app: { baseURL: '/' },
-    },
-    data: {},
-    state: {},
-  }
-
-  const app = win.document.createElement('div')
-  // this is a workaround for a happy-dom bug with ids beginning with _
-  app.id = 'nuxt-test'
-  win.document.body.appendChild(app)
-
-  win.IntersectionObserver
-    = win.IntersectionObserver
-      || class IntersectionObserver {
-        observe() {
-          // noop
-        }
-      }
-
-  const h3App = createApp()
-
-  const registry = new Set<string>()
-
-  if (__HST_COLLECT__) {
-    const {
-      toNodeListener,
-    } = await import('h3')
-    const {
-      createCall,
-      createFetch: createLocalFetch,
-    } = await import('unenv/runtime/fetch/index')
-    // @ts-expect-error TODO: fix in h3
-    const localCall = createCall(toNodeListener(h3App))
-    const localFetch = createLocalFetch(localCall, globalThis.fetch)
-
-    win.fetch = (init: string, options?: any) => {
-      if (typeof init === 'string' && registry.has(init)) {
-        init = `/_${init}`
-      }
-      return localFetch(init, options)
-    }
-  }
-
-  win.$fetch = createFetch({ fetch: win.fetch, Headers: win.Headers as any })
-
-  win.__registry = registry
-  win.__app = h3App
-
-  // @ts-expect-error no types
-  const result = await import('#app/entry')
-  await result.default()
-}

package/tsconfig.json

@@ -1,40 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    // Volar
-    "jsx": "preserve",
-    "lib": [
-      "ESNext",
-      "DOM"
-    ],
-    "rootDir": "src",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true,
-    "types": [
-      "node"
-    ],
-    "strictBindCallApply": true,
-    "strictFunctionTypes": true,
-    "alwaysStrict": true,
-    // Strict
-    "noImplicitAny": false,
-    "noImplicitThis": true,
-    "outDir": "dist",
-    "removeComments": false,
-    "sourceMap": false,
-    "allowSyntheticDefaultImports": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "preserveWatchOutput": true
-  },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "node_modules",
-    "generated/**/*",
-    "dist/**/*",
-    "src/**/*.spec.ts"
-  ]
-}