Next.js 15 + TailwindCSS + Storybook 세팅 이슈 해결하기

🚨 문제 상황

와 이거 때문에 진짜 미치는 줄 알았다.............

이거 거의 두 시간 동안 헤매고 있었어.......................... 흑그흑흘읍흑흑

 

1. postcss.config.mjs

Next.js 15 버전으로 프로젝트 생성하고 TailwindCSS도 자동으로 세팅이 됐다.

이제 npm create storybook@latest를 입력하고 Storybook을 설치하려고 하는데 이런 에러가 떴다.

=> Failed to build the preview
SB_FRAMEWORK_NEXTJS_0003 (IncompatiblePostCssConfigError): Incompatible PostCSS configuration format detected.

Next.js uses an array-based format for plugins which is not compatible with Vite:

// ❌ Incompatible format (used by Next.js)
const config = {
  plugins: ["@tailwindcss/postcss"],
};

Please transform your PostCSS config to use the object-based format, which is compatible with Next.js and Vite:

// ✅ Compatible format (works with Next.js and Vite)
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Original error: Invalid PostCSS Plugin found at: plugins[0]

(@.\postcss.config.mjs)

Storybook이 Next.js + Vite 프리뷰 빌드할 때 postcss.config.mjs 파일의 plugins 형식이 Next.js 기본 설정이랑 안 맞아서 그렇다고 한다.

근데 문제는 EMS로 하면 Storybook이 안된다고 뭐라 하고 CommonJS로 하면 Next.js app이 안된다고 뭐라고 하고.. (분노)

 

2. 스토리북 500 에러

Storybook 실행하면 docs나 컴포넌트 내용이 안 뜨고 console에 이렇게 떴다.

globals-runtime.js:4669  GET http://localhost:6006/iframe.html?viewMode=docs&id=configure-your-project--docs 500 (Internal Server Error)
Vj @ globals-runtime.js:4669
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
Vj @ globals-runtime.js:4671
ek @ globals-runtime.js:4974
dk @ globals-runtime.js:4787
ck @ globals-runtime.js:4777
dk @ globals-runtime.js:4857
Wk @ globals-runtime.js:5607
Pk @ globals-runtime.js:5582
Gk @ globals-runtime.js:5275
J @ globals-runtime.js:366
R @ globals-runtime.js:393

SB_CORE-SERVER_0002 (CriticalPresetLoadError): Storybook failed to load the following preset: @storybook\nextjs-vite\preset.

Please check whether your setup is correct, the Storybook dependencies (and their peer dependencies) are installed correctly and there are no package version clashes.

If you believe this is a bug, please open an issue on Github.

Error: Cannot find module '@storybook\nextjs-vite\preset'
Require stack:
- .\node_modules\storybook\dist\common\index.cjs
- .\node_modules\storybook\dist\cli\bin\index.cjs
- .\node_modules\storybook\dist\bin\index.cjs
- .\node_modules\storybook\bin\index.cjs
    at Function.<anonymous> (node:internal/modules/cjs/loader:1401:15)
    at Module._resolveFilename (.\node_modules\esbuild-register\dist\node.js:4794:36)
    at defaultResolveImpl (node:internal/modules/cjs/loader:1057:19)
    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1062:22)
    at Function._load (node:internal/modules/cjs/loader:1211:37)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
    at Module.require (node:internal/modules/cjs/loader:1487:12)
    at require (node:internal/modules/helpers:135:16)
    at interopRequireDefault (.\node_modules\storybook\dist\common\index.cjs:18796:11)

More info:

    at loadPreset (.\node_modules\storybook\dist\common\index.cjs:23615:13)

Broken build, fix the error above.
You may need to refresh the browser.

 

3. PostCSS 설정

위에서 정말 한~~~~참 빙빙 돌았기 때문에...

여기서부터 조금 희망이 보였다...

Failed to load PostCSS config (searchPath: E:/project/scriptopia-frontend): [SyntaxError] Unexpected token 'export'
E:\project\scriptopia-frontend\postcss.config.cjs:5
export default config;
^^^^^^

SyntaxError: Unexpected token 'export'
    at wrapSafe (node:internal/modules/cjs/loader:1662:18)
    at Module._compile (node:internal/modules/cjs/loader:1704:20)
    at node:internal/modules/cjs/loader:1895:10
    at Object.newLoader (E:\project\scriptopia-frontend\node_modules\esbuild-register\dist\node.js:2262:9)
    at extensions..js (E:\project\scriptopia-frontend\node_modules\esbuild-register\dist\node.js:4833:24)
    at Module.load (node:internal/modules/cjs/loader:1465:32)
    at Function._load (node:internal/modules/cjs/loader:1282:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
    at cjsLoader (node:internal/modules/esm/translators:266:5)

 

 

🥁 해결 방법

위 문제들이 하나씩 해결됐다기보단.. 이거 막으면 저거 터지고 저거 막으면 새로운 거 터지고 이랬어서 빙빙 돌고 제자리로 오고 이랬다가 저랬다가 이랬는데...

아무튼 아래대로 다 해주면 된다.

 

postcss.config.cjs로 바꾸고 내용도 아래처럼 수정한다.

tsconfig.json의 "include"에도 "**/*.cjs"를 추가한다.

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

 

아래 명령어를 실행한다.

npx storybook@latest upgrade

 

.storybook/preview.ts 파일에 globals.css를 import 한다.

• import '../app/globals.css';

 

.storybook/main.ts 파일을 아래 코드로 교체한다.

import type { StorybookConfig } from '@storybook/nextjs-vite';
import tailwindcss from '@tailwindcss/postcss';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-docs',
    '@storybook/addon-a11y',
    '@storybook/addon-vitest',
  ],
  framework: {
    name: '@storybook/nextjs-vite',
    options: {},
  },
  staticDirs: ['..\\public'],
  viteFinal: async (viteConfig) => {
    // TailwindCSS + PostCSS 적용
    viteConfig.css = {
      postcss: {
        plugins: [tailwindcss],
      },
    };
    return viteConfig;
  },
};
export default config;

 

ChatGPT가 처음에는 turbopack이 문제라고 해서 package.json의 dev script에서 --turbo도 지워봤는데 해결되지 않았었다.

그래도 혹시나 해서 일단 지우고 진행했는데 문제 다 해결한 후에 다시 turbopack으로 실행하니 잘 돌아간 거 보면 얘 문제는 아니었던 듯

---

 

후..... 도대체 discard를 몇 번이나 하고 Storybook을 몇 번이나 다시 깔았는지.....

그냥 중간에 Storybook 쓰지 말까.. 포기할까... 도 엄청 생각하고 ..

진짜 오기로 여기까지 왔다.........

 

 

[참고]

Storybook: Frontend workshop for UI development

(트러블 슈팅) Next.js 14 와 Storybook 에서 TailwindCSS 호환 이슈