테일윈드(Tailwind CSS) 설치를 2026년 6월 기준으로 Next.js·React(Vite)·순수 HTML 프레임워크별로 정리했습니다. v4로 바뀐 핵심 변경점(@tailwind 지시자 세 줄에서 CSS import 한 줄로, tailwind.config.js 대신 @theme 블록)과 PostCSS·Vite 플러그인 설정, 그리고 VS Code 자동완성과 색상 미리보기가 안 잡히는 IntelliSense 케이스를 직접 셋업해 해결한 점검 순서까지 단계별로 다룹니다. v3 프로젝트 마이그레이션 판단 기준도 함께 짚었습니다.
한 줄 요약: Tailwind CSS는 클래스 이름만으로 스타일을 입히는 유틸리티 우선 CSS 프레임워크인데, 2026년 기준 v4로 넘어오면서 설치 방식이 크게 바뀌었습니다. 예전처럼 tailwind.config.js와 @tailwind 지시자를 손으로 채우는 대신, CSS 파일 한 줄 import와 @theme 블록 중심으로 단순해졌습니다. 이 글에서는 Next.js·React(Vite)·순수 HTML 세 가지 환경에 각각 설치하는 절차를 정리하고, 제가 직접 셋업하며 막혔던 v4 변경점과 VS Code 자동완성이 안 잡히는 케이스를 해결한 방법까지 같이 다룹니다.
이 글이 필요한 사람
오래된 블로그 글을 따라 했더니 @tailwind 지시자에서 에러가 나서 막힌 분
Next.js·Vite·HTML 중 내 환경에 맞는 설치 절차만 빠르게 보고 싶은 분
VS Code에서 클래스 자동완성과 색상 미리보기가 안 떠서 답답한 분
v3로 만든 프로젝트를 v4로 올릴지 고민 중인 1인 개발자
※ 버전과 명령어는 2026년 6월 기준입니다. Tailwind는 메이저 변경이 잦으니 설치 직전 공식 문서에서 최신 절차를 다시 확인하시길 권합니다.
Tailwind CSS는 도대체 무엇이 다른가
Tailwind CSS는 미리 만들어진 작은 단위의 클래스를 조합해 화면을 꾸미는 방식입니다. 버튼 하나를 빨갛게 만들고 싶으면 별도의 CSS 파일을 열어 클래스를 정의하는 대신, HTML 요소에 bg-red-500 text-white px-4 py-2 rounded 처럼 클래스를 늘어놓습니다. 처음 보면 마크업이 지저분해 보이지만, 익숙해지면 CSS 파일과 HTML을 오가는 일이 사라져서 작업 속도가 확 빨라집니다.
제가 12개 사이트를 1인으로 운영하면서 가장 크게 체감한 장점은 클래스 이름을 짜내느라 고민할 필요가 없다는 점이었습니다. card-wrapper-inner-2 같은 의미 없는 이름을 더는 고민하지 않아도 됩니다. 다만 단점도 분명합니다. 같은 스타일 묶음을 여러 곳에 반복하면 마크업이 길어지므로, 컴포넌트로 분리하거나 @apply로 묶는 전략이 함께 필요합니다.
구분
전통적 CSS
Tailwind CSS
스타일 작성 위치
별도 CSS 파일
HTML 클래스에 직접
클래스 네이밍
매번 직접 고민
거의 불필요
파일 이동
HTML과 CSS 왕복
한 파일에서 끝
초기 학습
익숙함
유틸리티 클래스 암기 필요
최종 번들 크기
커지기 쉬움
사용한 클래스만 추출되어 작음
Tailwind CSS 설치·적용 완벽 가이드 (Next.js·React·HTML 프레임워크별) 관련 참고 이미지
v3에서 v4로, 설치가 이렇게 바뀌었습니다
한국 개발자분들이 가장 많이 막히는 지점이 바로 여기입니다. 검색해서 나오는 상당수의 설치 글이 v3 기준이라, 그대로 따라 하면 v4에서는 동작하지 않습니다. 저도 처음 v4로 새 프로젝트를 잡았을 때 옛날 방식대로 @tailwind base 한 줄을 넣었다가 빌드가 통째로 깨졌습니다. 무엇이 바뀌었는지 한눈에 정리하면 다음과 같습니다.
항목
v3 (예전)
v4 (현재)
CSS 진입점
@tailwind base/components/utilities 세 줄
@import "tailwindcss"; 한 줄
설정 파일
tailwind.config.js 필수
CSS의 @theme 블록 권장(설정 파일 선택)
PostCSS 플러그인
tailwindcss
@tailwindcss/postcss
Vite 연동
PostCSS 경유
@tailwindcss/vite 전용 플러그인
콘텐츠 경로(content)
config에 직접 지정
자동 감지(대부분 생략 가능)
핵심만 기억하면 됩니다. CSS 맨 위에 쓰던 @tailwind 지시자 세 줄은 v4에서 @import "tailwindcss"; 한 줄로 통째로 대체됐습니다. 그리고 색상·폰트 같은 디자인 토큰은 자바스크립트 설정 파일이 아니라 CSS 안의 @theme 블록에 적는 방향으로 무게중심이 옮겨졌습니다. 이 두 가지만 이해하면 v4 설치의 90%는 끝난 셈입니다.
막히는 케이스 메모. 빌드 중에 The `@tailwind base` directive is no longer supported 같은 에러가 보이면 거의 100% v3 글을 v4 프로젝트에 적용한 경우입니다. 해당 줄을 지우고 @import "tailwindcss"; 한 줄로 바꾸면 바로 해결됩니다. 반대로 v3 프로젝트인데 @import "tailwindcss"; 를 넣으면 또 안 되니, 먼저 package.json에서 설치된 버전부터 확인하는 게 순서입니다.
Next.js에 Tailwind 설치하는 절차
저는 tech.ambitstock을 포함한 사이트 대부분을 Next.js로 굴리고 있어서, 가장 자주 셋업하는 환경이 바로 이쪽입니다. 가장 깔끔한 방법은 프로젝트를 새로 만들 때 설치 마법사에서 Tailwind를 선택지로 켜는 것입니다. 그러면 진입 CSS와 PostCSS 설정이 자동으로 들어가 손댈 게 거의 없습니다. 아래는 새 프로젝트를 만드는 명령입니다.
Next.js 새 프로젝트 + Tailwind 자동 셋업
npx create-next-app@latest my-app
# 프롬프트에서 "Would you like to use Tailwind CSS?" 에 Yes 선택
cd my-app
npm run dev
이미 돌아가고 있는 Next.js 프로젝트에 뒤늦게 붙이는 경우라면 수동 설치가 필요합니다. v4 기준으로는 PostCSS 플러그인 패키지를 따로 받아야 한다는 점만 주의하면 됩니다. 아래 순서대로 진행하면 됩니다.
마지막으로 전역 CSS 파일(보통 app/globals.css 또는 styles/globals.css)의 맨 위에 import 한 줄을 넣고, 그 파일이 최상위 레이아웃에서 불러와지는지 확인합니다. App Router 기준으로는 app/layout.js 에서 globals.css를 import하면 됩니다.
app/globals.css (맨 위 한 줄)
@import "tailwindcss";
/* 여기서부터 내 커스텀 스타일이나 @theme 블록 추가 */
여기까지 마치고 npm run dev로 서버를 띄운 뒤, 아무 요소에나 className 으로 text-3xl font-bold text-blue-600 같은 클래스를 넣어 화면이 바뀌면 정상 설치된 것입니다. 저는 보통 페이지 제목 하나에 임시로 bg-red-500을 넣어 빨간 배경이 뜨는지로 확인하고, 확인 후 지웁니다. 이 한 번의 확인이 나중에 원인 모를 스타일 미적용으로 시간 날리는 걸 막아 줍니다.
Vite 기반 React에는 어떻게 붙일까
리액트(React)를 Vite로 돌리는 프로젝트라면 v4에서는 전용 Vite 플러그인을 쓰는 방식이 가장 빠릅니다. PostCSS를 거치지 않고 Vite에 직접 물리기 때문에 설정이 더 간단하고 빌드도 빠릅니다. 먼저 패키지를 설치합니다.
Vite + React에 Tailwind v4 설치
npm install -D tailwindcss @tailwindcss/vite
그다음 vite.config.js(또는 .ts) 파일에 Tailwind 플러그인을 추가합니다. 기존에 react 플러그인이 있다면 그 옆에 한 줄을 더 끼워 넣는 식입니다.
Tailwind CSS 설치·적용 완벽 가이드 (Next.js·React·HTML 프레임워크별) 관련 참고 이미지
vite.config.js
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import tailwindcss from "@tailwindcss/vite"
export default defineConfig({
plugins: [react(), tailwindcss()],
})
마지막으로 진입 CSS(보통 src/index.css)의 맨 위에 import 한 줄을 넣고, main.jsx에서 그 CSS가 불러와지는지 확인하면 끝입니다. Next.js와 다른 점은 PostCSS 설정 파일이 필요 없다는 것뿐이고, 진입 CSS에 @import "tailwindcss"; 한 줄을 넣는 흐름은 동일합니다.
src/index.css
@import "tailwindcss";
실측 팁. Vite 환경에서 클래스를 넣어도 스타일이 안 먹힐 때, 십중팔구 import "./index.css" 가 main.jsx에 빠져 있는 경우였습니다. CSS는 잘 만들었는데 정작 그 파일을 어디서도 불러오지 않으면 Tailwind 자체가 번들에 포함되지 않습니다. 스타일이 통째로 안 보이면 가장 먼저 이 import 줄부터 확인하세요.
빌드 도구 없는 순수 HTML에서 쓰는 두 가지 길
간단한 랜딩 페이지나 빠른 프로토타입처럼 빌드 도구를 쓰기 싫은 경우가 있습니다. 이때는 크게 두 갈래가 있습니다. 하나는 별도 설치 없이 CDN처럼 불러와 쓰는 방식이고, 다른 하나는 Tailwind CLI로 CSS를 직접 빌드해 정적 파일로 내보내는 방식입니다. 두 방식의 성격이 다르니 용도에 맞게 고르면 됩니다.
브라우저 직접 로드(CDN 스타일): HTML head에 스크립트 한 줄만 넣으면 바로 클래스가 동작합니다. 학습·데모·일회성 페이지에 적합하지만, 운영 사이트에는 권하지 않습니다. 매번 브라우저에서 전체 엔진을 실행하므로 속도와 안정성이 떨어집니다.
Tailwind CLI 빌드: 사용한 클래스만 추출한 작은 CSS 파일을 미리 만들어 두는 방식입니다. 운영용으로 쓸 거라면 이쪽이 정석입니다.
운영을 염두에 둔다면 CLI 방식을 권합니다. 아래는 입력 CSS를 만들어 두고, CLI로 결과 CSS를 뽑아내 HTML에서 일반 stylesheet로 거는 흐름입니다.
Tailwind CLI로 정적 CSS 빌드 (순수 HTML용)
npm install -D tailwindcss @tailwindcss/cli
# 입력 CSS(src/input.css) 맨 위에 @import "tailwindcss"; 한 줄을 넣어 둔 뒤
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch
이렇게 만들어진 dist/output.css 를 HTML의 head에서 평범한 link 태그로 걸면 끝입니다. --watch 옵션을 켜 두면 HTML에서 클래스를 추가할 때마다 자동으로 다시 빌드되어 편합니다. 저는 가벼운 정적 페이지를 빠르게 만들 때 이 방식을 자주 쓰는데, 결과 CSS가 실제 사용한 클래스만 담겨서 파일이 매우 작게 나오는 점이 마음에 듭니다.
VS Code 자동완성이 안 잡힐 때 점검 순서
설치는 됐는데 VS Code에서 클래스 자동완성과 색상 미리보기가 안 떠서 답답해하는 분이 정말 많습니다. 저도 v4로 넘어온 직후 이 문제로 한참 헤맸는데, 원인은 대체로 정해져 있습니다. 아래 순서대로 점검하면 거의 다 잡힙니다.
확장 설치 확인: VS Code 확장 마켓에서 Tailwind CSS IntelliSense 확장을 설치했는지부터 봅니다. 이게 없으면 자동완성이 아예 안 됩니다.
설정 파일 인식 문제: v4는 설정 파일 없이도 동작하지만, 일부 버전의 확장은 tailwind.config.js나 진입 CSS를 기준으로 프로젝트를 인식합니다. 자동완성이 안 뜨면 확장이 참고할 진입 CSS(@import "tailwindcss"; 가 들어간 파일)가 프로젝트 안에 있는지 확인합니다.
확장 재시작: 설치 직후엔 명령 팔레트(Cmd+Shift+P)에서 Developer: Reload Window를 한 번 실행해 줍니다. 의외로 이걸로 풀리는 경우가 많습니다.
파일 연결(associations): .jsx나 .tsx 같은 확장자에서 자동완성이 안 되면 settings.json에 editor.quickSuggestions의 strings를 켜고, 필요한 파일 타입을 tailwindCSS.includeLanguages로 매핑해 줍니다.
아래는 제가 실제로 쓰는 settings.json 보강 예시입니다. 문자열 안에서도 자동완성이 뜨도록 켜는 게 핵심입니다.
Tailwind CSS 설치·적용 완벽 가이드 (Next.js·React·HTML 프레임워크별) 관련 참고 이미지
막히는 케이스 메모. 클래스를 문자열 변수에 담거나 clsx 같은 유틸로 조합하면 확장이 그 안의 클래스를 못 알아채는 경우가 있습니다. 이럴 때는 tailwindCSS.experimental.classRegex 설정으로 어떤 패턴 안에서 클래스를 찾을지 알려 주면 자동완성이 살아납니다. 자동완성이 특정 코드 패턴에서만 안 된다면 변수에 담긴 클래스 문자열일 확률이 높습니다.
한국 개발자가 비용 면에서 알아둘 점
다행히 Tailwind CSS 자체는 오픈소스라 설치·사용에 돈이 들지 않습니다. 깃허브(GitHub)에서 누구나 받아 쓸 수 있고, 위에서 정리한 모든 설치 방식은 전부 무료입니다. 한국 카드로 따로 결제할 일도, 원화 환산이나 부가세(VAT 10%)를 신경 쓸 일도 없습니다. 이 점은 1인 개발자 입장에서 부담이 없어 좋습니다.
다만 비용이 발생할 수 있는 지점이 하나 있는데, 공식 유료 컴포넌트 모음인 Tailwind Plus(예전 Tailwind UI)입니다. 미리 디자인된 컴포넌트와 템플릿을 묶어 파는 별도 제품으로, 이건 유료입니다. 한국에서 해외 카드 결제로 사면 환율과 부가세가 청구서에 반영되니, 결제 직전 공식 페이지에서 최종 금액을 확인하는 편이 좋습니다. 2026년 6월 기준 가격과 라이선스 조건은 자주 바뀌므로 단정하지 않겠습니다. 정리하면, Tailwind 프레임워크 본체는 무료이고 비용은 선택적 유료 컴포넌트에서만 발생한다고 보면 됩니다.
v3 프로젝트, 지금 v4로 올려야 할까
이미 v3로 잘 돌아가는 프로젝트를 굳이 v4로 올려야 하느냐는 질문을 많이 받습니다. 제 경험상 판단 기준은 간단합니다. 새로 시작하는 프로젝트라면 처음부터 v4로 가는 게 맞습니다. 설치가 단순하고 빌드도 빠르며, 앞으로의 공식 문서가 모두 v4 기준이라 검색 결과와도 어긋나지 않습니다.
반면 운영 중인 v3 프로젝트라면 서두를 이유는 적습니다. v4는 진입 CSS 방식과 설정 위치가 바뀌었고, 일부 클래스 동작과 기본값도 미세하게 달라져서 마이그레이션 중 화면이 틀어질 수 있습니다. 공식 마이그레이션 도구가 자동으로 상당 부분을 바꿔 주긴 하지만, 변환 후엔 반드시 화면을 눈으로 검수해야 합니다. 저는 한가한 사이트 하나를 먼저 올려 부작용을 확인한 뒤, 문제가 없으면 나머지에 적용하는 식으로 진행했습니다.
지금 올릴 만한 경우: 신규 프로젝트, 학습용, 화면 검수 여유가 있을 때
미뤄도 되는 경우: 안정적으로 운영 중이고 일정이 빡빡할 때, v3 플러그인 의존이 많을 때
현재 설치된 버전이 v4일 가능성이 높습니다. v4에서는 @tailwind base/components/utilities 세 줄이 더는 지원되지 않고, 진입 CSS 맨 위에 @import "tailwindcss"; 한 줄을 넣는 방식으로 바뀌었습니다. 기존 세 줄을 지우고 import 한 줄로 교체하면 해결됩니다. 먼저 package.json에서 tailwindcss 버전을 확인한 뒤 그 버전에 맞는 문서를 보세요.
Next.js에 설치했는데 클래스가 화면에 전혀 안 먹힙니다
가장 흔한 원인은 진입 CSS(globals.css)가 레이아웃에서 import되지 않은 경우입니다. App Router라면 app/layout.js에서 globals.css를 불러오는지 확인하세요. 그다음 postcss.config 파일에 플러그인이 v4용 @tailwindcss/postcss로 등록돼 있는지, 진입 CSS 맨 위에 @import "tailwindcss"; 가 있는지 순서대로 점검하면 대부분 잡힙니다.
Vite와 PostCSS 방식 중 어느 쪽을 써야 하나요
Vite 프로젝트라면 전용 @tailwindcss/vite 플러그인을 쓰는 편이 더 빠르고 설정도 간단합니다. PostCSS 설정 파일을 따로 만들 필요가 없기 때문입니다. Next.js처럼 내부적으로 PostCSS를 쓰는 환경에서는 @tailwindcss/postcss 방식이 자연스럽습니다. 즉 빌드 도구가 무엇이냐에 따라 갈린다고 보면 됩니다.
VS Code에서 클래스 자동완성과 색상 미리보기가 안 떠요
먼저 Tailwind CSS IntelliSense 확장이 설치돼 있는지 확인하고, 명령 팔레트에서 Developer: Reload Window로 창을 한 번 새로고침하세요. 그래도 안 되면 settings.json에서 editor.quickSuggestions의 strings를 on으로 켜고, 필요하면 tailwindCSS.includeLanguages로 jsx·tsx 같은 파일 타입을 매핑해 줍니다. 변수에 담긴 클래스 문자열은 classRegex 설정으로 패턴을 알려 줘야 인식됩니다.
순수 HTML에 쓸 때 CDN과 CLI 빌드 중 무엇이 좋나요
학습이나 일회성 데모라면 브라우저에서 바로 불러오는 방식이 편하지만, 운영용 사이트에는 권하지 않습니다. 매번 브라우저에서 엔진을 실행해 속도와 안정성이 떨어지기 때문입니다. 실제 서비스에 쓸 거라면 Tailwind CLI로 사용한 클래스만 추출한 정적 CSS를 미리 빌드해 link 태그로 거는 방식이 정석입니다. 결과 파일도 훨씬 작게 나옵니다.
v4에서 tailwind.config.js는 이제 안 써도 되나요
v4는 색상·폰트 같은 디자인 토큰을 CSS의 @theme 블록에 적는 방식을 권장하므로, 많은 경우 자바스크립트 설정 파일 없이도 동작합니다. 다만 기존 설정을 그대로 쓰고 싶거나 일부 플러그인이 설정 파일을 필요로 하면 여전히 함께 사용할 수 있습니다. 새로 시작한다면 @theme 블록 중심으로 잡는 편이 v4 흐름에 맞습니다.
