TailwindCSS v4 인텔리센스 활성화 과정 정리

TailwindCSS v4가 기존의 v3와 구성 방식이 많이 달라졌습니다.

VSCode에서 인텔리센스가 제대로 동작하지 않는 문제가 있어 개인적으로 찾은 원인과 해결 방식을 정리해봅니다.

 

1. TailwindCSS v4에서의 기본 설정

v4에서는 포스트css, 테일윈드 컨피그와 같은 설정 파일을 별도로 구성하는 대신 CSS 파일에서 직접 스타일 설정을 구성합니다.

먼저 다음과 같이 엔트리 css 파일을 생성했습니다.

/* src/styles.css */

 

@import 'tailwindcss';

@import 'tailwindcss/preflight';

 

 

- tailwindcss/preflight는 이전 v3에서 @tailwind base; @tailwind components; @tailwind utilities; 를 통합한 역할을 합니다.

 

2. 커스텀 유틸리티 클래스 작성

먼저 기존과 동일하게 @layer 디렉티브를 이용하여 커스텀 클래스를 정의하려 했습니다.

@layer utilities {

  .custom-test {

    @apply bg-red-500;

  }

}

 

하지만 이렇게 정의된 클래스는 리액트 컴포넌트에서 타이핑 시 자동완성 힌트로 나타나지를 않았습니다. className="cus"까지 타이핑해도 추천이 뜨지 않았습니다.

function App() {

  return (

    <div>

      <h1 className=""></h1>

    </div>

  );

}

 

3. 기본 클래스조차 추천되지 않는 문제

심지어 Tailwind의 기본 클래스들도 추천되지 않는 상황이었기 때문에, 문제의 원인이 어디 있는지 다른 방향으로의 탐색이 필요했습니다. 

tailwindcss v4와 tailwindcss intelisence의 auto suggestion 등을 중점으로 검색을 진행했고, taiwlindcss의 깃허브 이슈와 스택오버플로우 등에서 공통적인 내용을 확인할 수 있었습니다. TailwindCSS v4는 별도의 tailwind.config.ts(js) 를 구성하지 않고 CSS 파일 하나로 설정을 대체하는 구조여서인지 현재 인텔리센스가 이를 바로 인식하지 못한 것으로 보였습니다.

 

https://stackoverflow.com/questions/79394239/vscode-tailwind-css-intellisense-autocompletion-and-suggestions-not-working-afte

VSCode Tailwind CSS Intellisense autocompletion and suggestions not working after installing Tailwind v4

https://github.com/tailwindlabs/tailwindcss-intellisense/issues/1054

V4 intellisense not working in a monorepo v0.12.9 and after · Issue #1054 · tailwindlabs/tailwindcss-intellisense

 

4. VSCode 설정 파일 구성

VSCode에서 TailwindCSS 인텔리센스가 올바른 CSS 기반의 설정을 인식하도록 .vscode/settings.json에 다음과 같이 설정을 추가해주었습니다.

{

  "tailwindCSS.experimental.configFile": "./src/styles.css",

}

그리고 VSCode의 확장 프로그램 호스트를 재시작하는 것으로 기본 클래스들의 인텔리센스가 정상 동작하는 것을 확인할 수 있었습니다.

 

5. 커스텀 클래스의 인텔리센스 문제

앞서 정의했던 @layer utilites 방식의 커스텀 클래스는 여전히 인텔리센스에 나타나지 않았습니다.

TailwindCSS v4에서는 @utility라는 새로운 지시어를 사용하도록 안내하고 있었습니다. 

@utility custom-class {

  @apply bg-red-500;

}

이렇게 작성하면 해당 커스텀 클래스 또한 인텔리센스에 포함되어 자동완성 힌트로 노출되는 것을 확인할 수 있었습니다.

https://tailwindcss.com/docs/adding-custom-styles#adding-custom-utilities

Adding custom styles - Core concepts

 

6. 정리

TailwindCSS v4는 설정 방식에 있어 큰 변화가 있었습니다.

• 별도의 config 파일 없이 CSS 파일 하나만으로 설정을 구성할 수 있게 된 점
• PostCSS 대신 Rust 기반의 Lightning CSS를 사용함으로써 빌드 속도가 빨라진 점
• 그에 따라 PostCSS에 대한 의존성이 제거된 점

이러한 변화 덕분에 프로젝트 루트에 불필요하게 설정 파일이 계속 늘어나는 것을 방지할 수 있고, 스타일을 수정했을 때 그 결과를 브라우저에서 더 빠르게 확인할 수 있는 개발 환경을 만들 수 있다고 생각합니다.

 

또한 @utility 지시어를 활용한 커스텀 클래스 선언은 TailwindCSS 특유의 길고 읽기 어려운 클래스명을 짧고 가독성 있게 작성할 수 있다는 점에서 매우 유용하다고 느꼈습니다. 여기에 디자인 토큰 기반의 네이밍을 적용하면 디자이너와 개발자 간의 소통을 원활하게 하고, UI 시스템의 일관성을 유지하는 데에도 도움이 된다고 생각합니다.