fix(administration): decouple Storybook from Shopware tsconfig

Author: shyim

CHANGELOG.md

@@ -26,6 +26,8 @@
   the stable `sw-page` host boundary remains.
 - Add a standalone Vue 3 Storybook component viewer with interactive stories for the complete
   `jetpack-*` catalog, deterministic DAL fixtures, generated docs, and a static documentation build.
+- Decouple the Storybook typecheck and Vite/esbuild build from Shopware's Administration
+  `tsconfig.json`, allowing documentation CI to build from a standalone Frosh Jetpack checkout.
 - Add a boot-order-safe global Administration CRUD API with typed DAL listings, detail/create forms,
   lifecycle hooks, association selectors, and immutable registration snapshots.
 - Add deterministic cross-plugin CRUD extensions for columns, cards, fields, row actions, bulk

docs/administration-components/storybook.md

@@ -20,6 +20,7 @@ navigation and overlays, and data and media.
 ## Build static documentation
 
 ```bash
+npm run storybook:typecheck
 npm run storybook:build
 ```
 
@@ -30,6 +31,11 @@ generated Storybook files in the Shopware plugin package.
 
 ## How the standalone environment works
 
+Storybook owns a self-contained TypeScript configuration and local declarations for its Twig imports
+and limited Shopware facade. Vite receives an explicit raw esbuild configuration, so neither the
+typecheck nor the production build resolves the Shopware Administration `tsconfig.json`. The viewer
+can therefore be built from a standalone Frosh Jetpack checkout in documentation CI.
+
 The Storybook bootstrap provides only the Shopware boundaries that the components intentionally use:
 
 - `Shopware.Component.register()` and `wrapComponentConfig()`;

src/Resources/app/administration/.storybook/html-shim.d.ts

@@ -0,0 +1,5 @@
+declare module "*.html.twig" {
+  const template: string;
+
+  export default template;
+}

src/Resources/app/administration/.storybook/main.ts

@@ -2,53 +2,57 @@ import type { StorybookConfig } from "@storybook/vue3-vite";
 import type { Plugin } from "vite";
 
 function jetpackTwigPlugin(): Plugin {
-    return {
-        name: "frosh-jetpack-storybook-twig",
-        enforce: "pre",
-        transform(source, id) {
-            if (!id.endsWith(".html.twig")) {
-                return null;
-            }
+  return {
+    name: "frosh-jetpack-storybook-twig",
+    enforce: "pre",
+    transform(source, id) {
+      if (!id.endsWith(".html.twig")) {
+        return null;
+      }
 
-            const template = source.replaceAll(
-                /\{%\s*(?:block\s+[A-Za-z0-9_]+|endblock)\s*%\}/g,
-                "",
-            );
+      const template = source.replaceAll(
+        /\{%\s*(?:block\s+[A-Za-z0-9_]+|endblock)\s*%\}/g,
+        "",
+      );
 
-            return {
-                code: `export default ${JSON.stringify(template)};`,
-                map: null,
-            };
-        },
-    };
+      return {
+        code: `export default ${JSON.stringify(template)};`,
+        map: null,
+      };
+    },
+  };
 }
 
 const config: StorybookConfig = {
-    stories: ["../stories/**/*.mdx", "../stories/**/*.stories.ts"],
-    addons: ["@storybook/addon-docs"],
-    framework: {
-        name: "@storybook/vue3-vite",
-        options: {},
-    },
-    core: {
-        disableTelemetry: true,
-    },
-    viteFinal(viteConfig) {
-        viteConfig.build = {
-            ...viteConfig.build,
-            target: "esnext",
-        };
-        viteConfig.esbuild = {
-            ...viteConfig.esbuild,
-            target: "esnext",
-        };
-        viteConfig.plugins = [
-            ...(viteConfig.plugins ?? []),
-            jetpackTwigPlugin(),
-        ];
+  stories: ["../stories/**/*.mdx", "../stories/**/*.stories.ts"],
+  addons: ["@storybook/addon-docs"],
+  framework: {
+    name: "@storybook/vue3-vite",
+    options: {},
+  },
+  core: {
+    disableTelemetry: true,
+  },
+  viteFinal(viteConfig) {
+    viteConfig.build = {
+      ...viteConfig.build,
+      target: "esnext",
+    };
+    viteConfig.esbuild = {
+      ...viteConfig.esbuild,
+      target: "esnext",
+      // Vite 6 still discovers a local tsconfig when this is an object. A raw JSON string
+      // deliberately bypasses the Shopware-dependent root tsconfig in standalone CI.
+      tsconfigRaw: JSON.stringify({
+        compilerOptions: {
+          useDefineForClassFields: true,
+        },
+      }),
+    };
+    viteConfig.plugins = [...(viteConfig.plugins ?? []), jetpackTwigPlugin()];
 
-        return viteConfig;
-    },
+    return viteConfig;
+  },
 };
 
 export default config;

src/Resources/app/administration/tsconfig.storybook.json

@@ -1,20 +1,25 @@
 {
-  "extends": "./tsconfig.json",
   "compilerOptions": {
-    "baseUrl": ".",
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
     "moduleResolution": "Bundler",
+    "baseUrl": ".",
+    "types": ["vite/client"],
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
     "noImplicitAny": false,
-    "types": ["node"]
+    "skipLibCheck": true
   },
   "include": [
     ".storybook/**/*.ts",
     ".storybook/**/*.d.ts",
     "stories/**/*.ts",
-    "src/component/jetpack-ui/**/*.ts",
-    "../../../../../../../src/Administration/Resources/app/administration/src/html-shim.d.ts",
-    "../../../../../../../src/Administration/Resources/app/administration/node_modules/vite/client.d.ts"
+    "src/component/jetpack-ui/**/*.ts"
   ],
-  "exclude": ["node_modules", "storybook-static", "src/**/*.spec.ts"],
-  "files": []
+  "exclude": ["node_modules", "storybook-static", "src/**/*.spec.ts"]
 }