[{"data":1,"prerenderedAt":17},["ShallowReactive",2],{"$fHyMlbu88GLsWPGuY2ox6EA8QlFARoEOOJjICTCXJmxE":3},{"uuid":4,"title":5,"summary":6,"content":7,"createdAt":8,"tags":9},"1d4e010e-ef25-4c8b-9373-24d3913f3bc8","Next.js 16 App Router 프로젝트에 Tailwind CSS 4 초기 설정 및 사용 방법","Next.js 16 App Router 프로젝트에 Tailwind CSS 4를 설정하려면, 먼저 필요한 패키지를 설치하고 설정 파일을 구성해야 합니다. 이후 전역 CSS 파일에 Tailwind 지시문을 추가하고, PostCSS가 Tailwind를 처리하도록 구성하면 Tailwind CSS 클래스를 사용할 수 있습니다.","Next.js 16 App Router 프로젝트에 Tailwind CSS 4(프리뷰 버전)를 통합하는 과정은 몇 가지 간단한 설정 단계를 거칩니다. 이 가이드는 Tailwind CSS 4의 최신 기능을 활용하기 위해 필요한 설치, 설정 파일 구성, 그리고 전역 CSS 통합 방법을 안내합니다.\n\n## Tailwind CSS 4 및 의존성 설치\n\n가장 먼저 프로젝트에 Tailwind CSS 4와 그 의존성인 PostCSS, Autoprefixer를 설치해야 합니다. Tailwind CSS 4는 현재 프리뷰 버전이므로 `@next` 태그를 사용하여 설치합니다. 프로젝트에서 `pnpm`을 사용하고 있으므로 `pnpm` 명령어를 기준으로 설명합니다.\n\n```bash\npnpm add -D tailwindcss@next postcss autoprefixer\n```\n\n*   `tailwindcss@next`: Tailwind CSS 4의 프리뷰 버전을 설치합니다.\n*   `postcss`: CSS를 변환하는 도구입니다. Tailwind CSS는 PostCSS 플러그인으로 동작합니다.\n*   `autoprefixer`: PostCSS 플러그인으로, CSS에 자동으로 벤더 프리픽스(예: `-webkit-`)를 추가하여 브라우저 호환성을 높여줍니다.\n\n## Tailwind CSS 설정 파일 생성 및 구성\n\n설치가 완료되면, Tailwind CSS의 설정 파일을 생성해야 합니다. TypeScript 프로젝트이므로 `tailwind.config.ts` 파일을 생성합니다. 이 파일은 Tailwind CSS가 스캔할 파일 경로와 커스텀 테마 등을 정의하는 데 사용됩니다.\n\n```bash\npnpm tailwindcss init -t ts\n```\n\n이 명령어를 실행하면 프로젝트 루트에 `tailwind.config.ts` 파일이 생성됩니다. 생성된 파일을 열어 `content` 배열에 Tailwind CSS 클래스를 사용하는 모든 파일의 경로를 추가해야 합니다. App Router 구조에서는 `src\u002Fapp` 및 `src\u002Fcomponents` 디렉토리 내의 파일들을 포함하는 것이 일반적입니다.\n\n```ts\n\u002F\u002F tailwind.config.ts\nimport type { Config } from 'tailwindcss';\n\nconst config: Config = {\n  content: [\n    '.\u002Fsrc\u002Fpages\u002F**\u002F*.{js,ts,jsx,tsx,mdx}', \u002F\u002F Pages Router를 사용한다면 필요, App Router만 사용시 제외 가능\n    '.\u002Fsrc\u002Fcomponents\u002F**\u002F*.{js,ts,jsx,tsx,mdx}',\n    '.\u002Fsrc\u002Fapp\u002F**\u002F*.{js,ts,jsx,tsx,mdx}',\n  ],\n  theme: {\n    extend: {},\n  },\n  plugins: [],\n};\n\nexport default config;\n```\n\n## PostCSS 설정 파일 구성 (`postcss.config.mjs`)\n\nNext.js는 PostCSS를 사용하여 CSS를 처리합니다. 따라서 Tailwind CSS와 Autoprefixer가 PostCSS를 통해 작동하도록 `postcss.config.mjs` 파일을 설정해야 합니다. 이 파일은 프로젝트 루트에 생성합니다.\n\n```js\n\u002F\u002F postcss.config.mjs\nexport default {\n  plugins: {\n    tailwindcss: {},\n    autoprefixer: {},\n  },\n};\n```\n\n*   `tailwindcss`: PostCSS에 Tailwind CSS 플러그인을 활성화합니다.\n*   `autoprefixer`: PostCSS에 Autoprefixer 플러그인을 활성화합니다.\n\n## 전역 CSS에 Tailwind 지시문 추가\n\n이제 Tailwind CSS의 기본 스타일, 컴포넌트, 유틸리티 클래스를 프로젝트에 주입해야 합니다. 이를 위해 Next.js App Router의 전역 CSS 파일인 `src\u002Fapp\u002Fglobals.css`에 Tailwind CSS 지시문을 추가합니다.\n\n```css\n\u002F* src\u002Fapp\u002Fglobals.css *\u002F\n@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n\u002F* 여기에 사용자 정의 CSS를 추가할 수 있습니다 *\u002F\n```\n\n`src\u002Fapp\u002Flayout.tsx` 파일에서 `globals.css`를 임포트하고 있는지 확인하세요.\n\n```tsx\n\u002F\u002F src\u002Fapp\u002Flayout.tsx\nimport type { Metadata } from 'next';\nimport '.\u002Fglobals.css'; \u002F\u002F Tailwind CSS가 포함된 전역 CSS 임포트\n\nexport const metadata: Metadata = {\n  title: 'My Next.js App',\n  description: 'Generated by create next app',\n};\n\nexport default function RootLayout({\n  children,\n}: { \n  children: React.ReactNode;\n}) {\n  return (\n    \u003Chtml lang=\"ko\">\n      \u003Cbody>{children}\u003C\u002Fbody>\n    \u003C\u002Fhtml>\n  );\n}\n```\n\n## Tailwind CSS 클래스 사용 및 동작 확인\n\n모든 설정이 완료되었으므로, 이제 Next.js 컴포넌트에서 Tailwind CSS 클래스를 사용하여 스타일을 적용할 수 있습니다. 프로젝트를 개발 모드로 실행하여 변경 사항을 확인합니다.\n\n```bash\npnpm dev\n```\n\n예를 들어, `src\u002Fapp\u002Fpage.tsx` 파일에서 다음과 같이 Tailwind CSS 클래스를 사용할 수 있습니다.\n\n```tsx\n\u002F\u002F src\u002Fapp\u002Fpage.tsx\nexport default function Home() {\n  return (\n    \u003Cmain className=\"flex min-h-screen flex-col items-center justify-between p-24 bg-gray-100\">\n      \u003Ch1 className=\"text-4xl font-bold text-blue-600 mb-8\">Hello, Tailwind CSS 4!\u003C\u002Fh1>\n      \u003Cp className=\"text-lg text-gray-700\">Next.js 16 App Router와 함께 성공적으로 설정되었습니다.\u003C\u002Fp>\n      \u003Cbutton className=\"mt-4 px-6 py-3 bg-green-500 text-white rounded-lg shadow-md hover:bg-green-600 transition-colors\">\n        버튼입니다\n      \u003C\u002Fbutton>\n    \u003C\u002Fmain>\n  );\n}\n```\n\n브라우저에서 페이지를 확인하면, Tailwind CSS 클래스가 정상적으로 적용되어 스타일이 나타나는 것을 볼 수 있습니다.\n\n## 흔히 하는 실수 및 주의점\n\n*   **`content` 경로 누락 또는 오타**: `tailwind.config.ts` 파일의 `content` 배열에 Tailwind CSS 클래스를 사용하는 모든 파일의 경로가 정확히 포함되어야 합니다. 그렇지 않으면 Tailwind CSS가 해당 파일의 클래스를 스캔하지 못해 스타일이 적용되지 않습니다.\n*   **`postcss.config.mjs` 파일명 또는 위치 오류**: 파일 이름이 `postcss.config.mjs`여야 하며, 프로젝트 루트 디렉토리에 위치해야 합니다. `js` 대신 `mjs` 확장자를 사용하는 것이 중요합니다.\n*   **`@tailwind` 지시문 누락**: `src\u002Fapp\u002Fglobals.css` 파일에 `@tailwind base;`, `@tailwind components;`, `@tailwind utilities;` 지시문이 정확히 포함되어 있는지 확인하세요.\n*   **Tailwind CSS 4는 프리뷰 버전**: 이 가이드에서 다룬 Tailwind CSS 4는 아직 개발 중인 프리뷰 버전입니다. API 변경이나 예기치 않은 동작이 발생할 수 있으므로, 프로덕션 환경에 적용하기 전에는 충분한 테스트를 거치거나 안정 버전을 사용하는 것을 고려해야 합니다.","2026-08-19T14:00:56.887+09:00",[10,11,12,13,14,15,16],"App Router","CSS","Next-js","Tailwind CSS 4","기술 가이드","설정","프론트엔드",1788152655817]