Vite 프로젝트에 Tailwind CSS 설치하고 VS Code 확장 설정하기

이전 글에서 Vite + React + TypeScript 프로젝트에 ESLint, Prettier, Error Lens, Pretty TypeScript Errors를 설정했죠. 이번에는 같은 프로젝트에 Tailwind CSS를 얹고, 작업을 편하게 만들어 주는 VS Code 확장 두 가지를 세팅합니다.

다루는 내용은 이렇습니다.

1. Vite 프로젝트에 Tailwind CSS 설치
2. Tailwind CSS IntelliSense — 클래스 자동완성과 미리보기
3. Tailwind Fold — 긴 클래스 문자열 접기

시작하기 전에

• 이전 글에서 만든 Vite + React + TypeScript 프로젝트(my-app)가 있어야 합니다
• VS Code가 설치되어 있어야 합니다
• 예상 소요 시간: 약 10분

---

1. Tailwind CSS 설치

1-1. 패키지 설치

프로젝트 폴더에서 아래 명령을 실행합니다.

복사
cd my-app
npm install -D tailwindcss @tailwindcss/vite

각 패키지의 역할은 다음과 같습니다.

• tailwindcss — Tailwind CSS 본체
• @tailwindcss/vite — Vite 전용 플러그인. Tailwind가 Vite 빌드 과정에 끼어들 수 있게 해 줍니다

1-2. Vite 설정에 플러그인 추가

vite.config.ts 파일을 열고, Tailwind 플러그인을 추가합니다.

복사
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
  ],
})

기존에 react() 플러그인만 있었을 텐데, 그 아래에 tailwindcss()를 한 줄 추가하면 됩니다.

1-3. CSS에 Tailwind 연결

src/index.css 파일을 열고, 기존 내용을 전부 지운 뒤 아래 한 줄만 남깁니다.

복사
@import "tailwindcss";

이 한 줄이 Tailwind의 모든 유틸리티 클래스를 불러와요. 예전에는 @tailwind base; @tailwind components; @tailwind utilities; 세 줄을 써야 했는데, Tailwind CSS v4부터는 이렇게 간결해졌습니다.

1-4. 동작 확인

src/App.tsx를 열고 내용을 아래처럼 바꿔 보세요.

복사
function App() {
  return (
    <div className="bg-gray-100 min-h-screen flex items-center justify-center">
      <div className="bg-white rounded-xl shadow-lg p-8 max-w-md text-center">
        <h1 className="text-3xl font-bold text-gray-800 mb-4">
          Tailwind 설치 완료!
        </h1>
        <p className="text-gray-600">
          회색 배경에 흰색 카드가 보이면 성공입니다.
        </p>
      </div>
    </div>
  )
}

export default App

개발 서버를 실행합니다.

복사
npm run dev

확인하기: 브라우저에서 http://localhost:5173을 열었을 때 회색 배경 위에 흰색 카드가 가운데 정렬되어 보이면 Tailwind가 잘 동작하고 있는 겁니다.

만약 스타일이 전혀 적용되지 않는다면:

1. src/index.css에 @import "tailwindcss"; 한 줄만 있는지 확인하세요
2. src/main.tsx에서 import './index.css'가 있는지 확인하세요 (Vite 기본 템플릿에는 포함되어 있습니다)
3. vite.config.ts에 tailwindcss() 플러그인이 들어 있는지 확인하세요

---

2. Tailwind CSS IntelliSense — 클래스 자동완성

왜 필요한가요?

Tailwind에는 유틸리티 클래스가 수천 개 있어요. bg-blue-500인지 bg-blue-600인지, px-4가 몇 px인지 매번 문서를 찾아보기 힘들잖아요. Tailwind CSS IntelliSense는 클래스를 입력할 때 자동완성으로 보여 주고, 마우스를 올리면 실제 CSS 속성까지 미리 보여 줍니다.

Tailwind 팀이 직접 만들고 관리하는 공식 확장이에요.

2-1. 설치

마켓플레이스에서 Tailwind CSS IntelliSense (Tailwind Labs)를 설치합니다.

설치만 하면 바로 동작합니다. Tailwind가 프로젝트에 설치되어 있으면 자동으로 인식해요.

2-2. 주요 기능 세 가지

자동완성

className=" 뒤에 글자를 치기 시작하면 일치하는 클래스 목록이 드롭다운으로 뜹니다. 예를 들어 bg-까지 치면 bg-white, bg-gray-100, bg-blue-500 같은 선택지가 나열돼요.

호버 미리보기

이미 작성된 클래스 위에 마우스를 올리면 그 클래스가 실제로 어떤 CSS로 변환되는지 팝업으로 보여 줍니다. p-4에 올려 보면 padding: 1rem; /* 16px */ 같은 식으로 나와요.

린팅

존재하지 않는 클래스를 쓰면 경고를 띄워 줍니다. bg-bule-500 같은 오타를 바로 잡을 수 있어요. 충돌하는 클래스(예: p-4와 px-2를 동시에 쓴 경우)도 알려 줍니다.

2-3. VS Code 설정 추가

이전 글에서 만든 .vscode/settings.json에 Tailwind 관련 설정을 추가합니다.

복사
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "tailwindCSS.includeLanguages": {
    "typescriptreact": "html"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  }
}

새로 추가된 두 줄의 의미는 이렇습니다.

• tailwindCSS.includeLanguages — TSX 파일에서도 Tailwind 자동완성이 동작하게 합니다
• editor.quickSuggestions.strings — 문자열 안에서도 자동완성 제안이 뜨게 합니다. 이 설정이 꺼져 있으면 className="" 안에서 자동완성이 동작하지 않을 수 있어요

2-4. 추천 확장 목록 업데이트

.vscode/extensions.json에 Tailwind 관련 확장을 추가합니다.

복사
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "usernamehw.errorlens",
    "yoavbls.pretty-ts-errors",

  ]
}

2-5. 동작 확인

src/App.tsx를 열고 className=" 뒤에 text-를 타이핑해 보세요. text-sm, text-lg, text-gray-500 같은 자동완성 목록이 뜨면 잘 동작하고 있는 겁니다.

이미 작성된 bg-gray-100 위에 마우스를 올려 보세요. background-color: oklch(0.967 0.003 264.542); 같은 실제 CSS 값이 팝업으로 보이면 호버 미리보기도 정상입니다.

---

3. Tailwind Fold — 긴 클래스 접기

왜 필요한가요?

Tailwind를 쓰다 보면 한 요소에 클래스가 10개, 20개씩 붙는 일이 자주 생깁니다. 그러면 코드가 이렇게 돼요.

복사
<button className="mt-6 bg-blue-500 text-white px-6 py-2 rounded-lg hover:bg-blue-600 active:bg-blue-700 transition-colors duration-200 font-medium shadow-md hover:shadow-lg disabled:opacity-50 disabled:cursor-not-allowed">
  시작하기
</button>

코드 한 줄이 화면 밖으로 길게 늘어져서 스크롤해야 끝이 보이죠. 정작 봐야 할 JSX 구조는 이 긴 문자열에 묻혀 버립니다.

Tailwind Fold는 이 긴 클래스 문자열을 ...처럼 접어서 보여 줍니다. 커서를 그 줄에 가져가면 다시 펼쳐져서 편집할 수 있어요.

3-1. 설치

마켓플레이스에서 Tailwind Fold를 설치합니다.

설치 후 바로 동작합니다. 긴 className 값이 접혀서 보이면 성공이에요.

3-2. 접기/펼치기 토글

수동으로 접기를 켜거나 끄고 싶을 때는 명령 팔레트(Ctrl+Shift+P)에서 Tailwind Fold를 검색하면 토글 명령이 나옵니다.

코드 리뷰할 때 전체 클래스를 한눈에 봐야 한다면 잠시 끄고, 다시 구조를 파악할 때 켜면 편해요.

---

전체 설정 파일 체크리스트

이전 글과 이번 글의 설정을 합치면 프로젝트에 아래 파일이 갖춰져 있어야 해요.

복사
my-app/
├── .vscode/
│   ├── settings.json       ← ESLint + Prettier + Tailwind 설정
│   └── extensions.json     ← 추천 확장 6개
├── eslint.config.js        ← ESLint 규칙
├── .prettierrc             ← Prettier 스타일 설정
├── .prettierignore         ← Prettier 제외 파일
├── vite.config.ts          ← Vite + React + Tailwind 플러그인
├── src/
│   └── index.css           ← @import "tailwindcss"
├── package.json
└── ...

---

마무리

Tailwind CSS 설치 자체는 패키지 두 개 깔고 설정 세 줄 고치면 끝이에요. 오히려 확장 기능 설정에 시간이 더 걸리는데, 한 번 해 두면 이후 작업이 확 편해집니다.

IntelliSense 없이 Tailwind를 쓰면 공식 문서를 계속 왔다 갔다 하게 되는데, 자동완성과 호버 미리보기가 있으면 편집기 안에서 다 해결돼요. Tailwind Fold는 처음에 "이게 꼭 필요한가?" 싶지만, 컴포넌트가 커지기 시작하면 없으면 불편합니다.

다음 글에서는 이 환경 위에서 실제 React 컴포넌트를 만들어 볼 예정이에요.

문제 해결

Tailwind 클래스 자동완성이 안 뜹니다

1. Tailwind CSS IntelliSense 확장이 설치되어 있는지 확인하세요
2. .vscode/settings.json에 "editor.quickSuggestions": { "strings": "on" } 설정이 있는지 확인하세요. 이 설정이 꺼져 있으면 className="" 안에서 자동완성이 동작하지 않을 수 있어요
3. 프로젝트에 tailwindcss 패키지가 설치되어 있어야 합니다 (package.json의 devDependencies 확인)

Tailwind 스타일이 적용되지 않습니다

1. src/index.css에 @import "tailwindcss";가 있는지 확인하세요
2. vite.config.ts에 tailwindcss() 플러그인이 포함되어 있는지 확인하세요
3. 개발 서버를 다시 시작해 보세요 (Ctrl+C로 끄고 npm run dev 다시 실행)

Tailwind Fold가 동작하지 않습니다

확장이 설치되었는데도 접히지 않으면, VS Code를 한 번 재시작해 보세요. 그래도 안 되면 명령 팔레트(Ctrl+Shift+P)에서 "Tailwind Fold: Toggle" 명령으로 수동 활성화를 시도합니다.