NextJS-Vite: Automatically fix bad PostCSS configuration

code/frameworks/nextjs-vite/package.json

@@ -87,6 +87,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "lilconfig": "^3.0.0",
     "next": "^15.2.3",
     "postcss-load-config": "^6.0.1",
     "semver": "^7.3.5",

code/frameworks/nextjs-vite/src/find-postcss-config.ts

@@ -0,0 +1,139 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+
+import { getProjectRoot } from 'storybook/internal/common';
+import { IncompatiblePostCssConfigError } from 'storybook/internal/server-errors';
+
+import config from 'lilconfig';
+import postCssLoadConfig from 'postcss-load-config';
+
+type Options = import('lilconfig').Options;
+
+const require = createRequire(import.meta.url);
+
+async function loader(filepath: string) {
+  return require(filepath);
+}
+
+const withLoaders = (options: Options = {}) => {
+  const moduleName = 'postcss';
+
+  return {
+    ...options,
+    loaders: {
+      ...options.loaders,
+      '.cjs': loader,
+      '.cts': loader,
+      '.js': loader,
+      '.mjs': loader,
+      '.mts': loader,
+      '.ts': loader,
+    },
+    searchPlaces: [
+      ...(options.searchPlaces ?? []),
+      'package.json',
+      `.${moduleName}rc`,
+      `.${moduleName}rc.json`,
+      `.${moduleName}rc.ts`,
+      `.${moduleName}rc.cts`,
+      `.${moduleName}rc.mts`,
+      `.${moduleName}rc.js`,
+      `.${moduleName}rc.cjs`,
+      `.${moduleName}rc.mjs`,
+      `${moduleName}.config.ts`,
+      `${moduleName}.config.cts`,
+      `${moduleName}.config.mts`,
+      `${moduleName}.config.js`,
+      `${moduleName}.config.cjs`,
+      `${moduleName}.config.mjs`,
+    ],
+  } satisfies Options;
+};
+
+/**
+ * Find PostCSS config file path (without loading the config)
+ *
+ * @param {String} path Config Path
+ * @param {Object} options Config Options
+ * @returns {Promise<string | null>} Config file path or null if not found
+ */
+async function postCssFindConfig(path: string, options: Options = {}) {
+  const result = await config.lilconfig('postcss', withLoaders(options)).search(path);
+
+  return result ? result.filepath : null;
+}
+
+export { postCssLoadConfig };
+
+/**
+ * Normalizes PostCSS configuration for NextJS compatibility.
+ *
+ * This function handles the incompatibility between NextJS's PostCSS plugin format and Storybook's
+ * requirements. NextJS uses array format for plugins while Storybook expects object format.
+ *
+ * Process:
+ *
+ * 1. First attempts to load the config as-is
+ * 2. If that fails due to "Invalid PostCSS Plugin found" error, modifies the config file to convert
+ *    array format to object format (e.g., ["@tailwindcss/postcss"] becomes {
+ *    "@tailwindcss/postcss": {} })
+ * 3. Retries loading with the modified config
+ *
+ * @param searchPath - Directory path to search for PostCSS config
+ * @returns Promise<boolean> - true if config loads successfully (or no config found), false if
+ *   config exists but cannot be loaded
+ * @throws {IncompatiblePostCssConfigError} - When config cannot be fixed automatically
+ * @sideEffect Modifies the PostCSS config file on disk when fixing plugin format
+ */ export const normalizePostCssConfig = async (searchPath: string): Promise<boolean> => {
+  const configPath = await postCssFindConfig(searchPath);
+  if (!configPath) {
+    return true;
+  }
+
+  let error: Error | undefined;
+
+  // First attempt: try loading config as-is
+  try {
+    await postCssLoadConfig({}, searchPath, { stopDir: getProjectRoot() });
+    return true; // Success!
+  } catch (e: unknown) {
+    if (e instanceof Error) {
+      error = e;
+    }
+  }
+
+  if (!error) {
+    return true;
+  }
+
+  // No config found is not an error we need to handle
+  if (error.message.includes('No PostCSS Config found')) {
+    return true;
+  }
+
+  // NextJS uses an incompatible format for PostCSS plugins, we make an attempt to fix it
+  if (error.message.includes('Invalid PostCSS Plugin found')) {
+    // Second attempt: try with modified config
+    const originalContent = await readFile(configPath, 'utf8');
+    try {
+      const modifiedContent = originalContent.replace(
+        'plugins: ["@tailwindcss/postcss"]',
+        'plugins: { "@tailwindcss/postcss": {} }'
+      );
+
+      // Write the modified content
+      await writeFile(configPath, modifiedContent, 'utf8');
+
+      // Retry loading the config
+      await postCssLoadConfig({}, searchPath, { stopDir: getProjectRoot() });
+      return true; // Success with modified config!
+    } catch (e: any) {
+      // We were unable to fix the config, so we change the file back to the original content
+      await writeFile(configPath, originalContent, 'utf8');
+      // and throw an error
+      throw new IncompatiblePostCssConfigError({ error });
+    }
+  }
+
+  return false;
+};

code/frameworks/nextjs-vite/src/preset.ts

@@ -3,16 +3,14 @@ import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { getProjectRoot } from 'storybook/internal/common';
-import { IncompatiblePostCssConfigError } from 'storybook/internal/server-errors';
 import type { PresetProperty } from 'storybook/internal/types';
 
 import type { StorybookConfigVite } from '@storybook/builder-vite';
 import { viteFinal as reactViteFinal } from '@storybook/react-vite/preset';
 
-import postCssLoadConfig from 'postcss-load-config';
 import semver from 'semver';
 
+import { normalizePostCssConfig } from './find-postcss-config';
 import type { FrameworkOptions } from './types';
 import { getNextjsVersion } from './utils';
 
@@ -63,17 +61,11 @@ export const optimizeViteDeps = [
 export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, options) => {
   const reactConfig = await reactViteFinal(config, options);
 
-  try {
-    const inlineOptions = config.css?.postcss;
-    const searchPath = typeof inlineOptions === 'string' ? inlineOptions : config.root;
-    await postCssLoadConfig({}, searchPath, { stopDir: getProjectRoot() });
-  } catch (e: any) {
-    if (!e.message.includes('No PostCSS Config found')) {
-      // This is a custom error that we throw when the PostCSS config is invalid
-      if (e.message.includes('Invalid PostCSS Plugin found')) {
-        throw new IncompatiblePostCssConfigError({ error: e });
-      }
-    }
+  const inlineOptions = config.css?.postcss;
+  const searchPath = typeof inlineOptions === 'string' ? inlineOptions : config.root;
+
+  if (searchPath) {
+    await normalizePostCssConfig(searchPath);
   }
 
   const { nextConfigPath } = await options.presets.apply<FrameworkOptions>('frameworkOptions');

code/yarn.lock

@@ -6564,6 +6564,7 @@ __metadata:
     "@storybook/react": "workspace:*"
     "@storybook/react-vite": "workspace:*"
     "@types/node": "npm:^22.0.0"
+    lilconfig: "npm:^3.0.0"
     next: "npm:^15.2.3"
     postcss-load-config: "npm:^6.0.1"
     semver: "npm:^7.3.5"
@@ -18126,7 +18127,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"lilconfig@npm:^3.1.1":
+"lilconfig@npm:^3.0.0, lilconfig@npm:^3.1.1":
   version: 3.1.3
   resolution: "lilconfig@npm:3.1.3"
   checksum: 10c0/f5604e7240c5c275743561442fbc5abf2a84ad94da0f5adc71d25e31fa8483048de3dcedcb7a44112a942fed305fd75841cdf6c9681c7f640c63f1049e9a5dcc