Tailwind CSS Unknown at rule 경고 해결: VS Code와 PostCSS 설정 확인

가장 먼저 빌드가 되는지 확인하기

에디터에 Unknown at rule이 보여도 개발 서버가 정상 동작할 수 있습니다.

pnpm dev

또는 production build를 확인합니다.

pnpm build

결과를 먼저 두 가지로 나눕니다.

A. 빌드는 성공하고 VS Code에만 경고가 보임
→ 에디터 언어 지원 문제 가능성

B. 빌드 자체가 실패
→ Tailwind/PostCSS 설정 문제 가능성

이 구분 없이 설정 파일을 계속 수정하면 정상 빌드를 오히려 깨뜨릴 수 있습니다.

왜 VS Code가 경고하는가

일반 CSS 검사기는 표준 CSS 문법을 기준으로 분석합니다.

Tailwind는 자체 at-rule과 함수를 사용할 수 있습니다.

예를 들어 현재 Tailwind 문법에서는 다음과 같은 구문을 볼 수 있습니다.

@import "tailwindcss";

@theme {
  --color-brand: #111111;
}

에디터가 Tailwind 문법을 알지 못하면 @theme을 알 수 없는 at-rule로 표시할 수 있습니다.

Tailwind CSS IntelliSense 확인

VS Code에서는 공식 Tailwind CSS IntelliSense 확장을 사용할 수 있습니다.

확장이 활성화되어 있는지 확인하고 현재 workspace에서 동작하는지 확인합니다.

확장 설치 여부만 보고 끝내지 말고 다음도 확인합니다.

현재 열어 둔 폴더가 프로젝트 루트인가
Tailwind 파일이 실제 workspace 안에 있는가
확장이 disabled 상태가 아닌가
CSS language mode가 예상대로 동작하는가

Tailwind 공식 문서는 전용 언어 모드가 자체 at-rule과 함수의 syntax를 지원한다고 안내합니다.

실제 빌드가 실패한다면 PostCSS 확인

PostCSS 방식으로 Tailwind를 사용하는 프로젝트라면 현재 사용 중인 Tailwind 주요 버전에 맞는 plugin 구성을 확인합니다.

예시:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

CSS에서는 현재 설치 방식에 맞는 import를 사용합니다.

@import "tailwindcss";

이 예제는 현재 공식 문서의 PostCSS 설치 흐름을 기준으로 한 형태입니다.

과거 Tailwind 버전의 설정 파일이나 directive 예제를 그대로 섞지 않습니다.

버전 혼합이 문제를 만든다

검색 결과에는 서로 다른 Tailwind 세대의 예제가 함께 나옵니다.

다음 조합을 그대로 섞으면 문제가 생길 수 있습니다.

예전 tailwind.config.js 예제
현재 @theme 예제
예전 PostCSS plugin 이름
현재 @tailwindcss/postcss

그래서 먼저 설치된 버전과 공식 문서를 확인합니다.

pnpm list tailwindcss

labs에서 재현하기

TaskFlow 메인 프로젝트가 Tailwind를 사용하지 않는다면 메인 앱에 억지로 설치하지 않습니다.

labs/
└─ tailwind-at-rule/

이 lab에서 다음 두 상태를 따로 확인합니다.

1. 빌드 정상 + 에디터 경고
2. PostCSS 설정 오류 + 빌드 실패

두 문제를 같은 해결책으로 처리하지 않는 것이 이번 글의 핵심입니다.

CSS validation을 끄면 해결인가

일반 CSS validation을 끄면 경고가 사라질 수 있습니다.

하지만 모든 프로젝트에서 전역 validation을 끄는 방식은 권장하지 않습니다.

먼저 Tailwind 공식 extension과 현재 파일의 언어 모드가 문제를 해결할 수 있는지 확인합니다.

설정 변경이 필요하다면 workspace 범위로 제한하고 이유를 문서화합니다.

Unknown at rule 진단 순서

1. pnpm dev 또는 pnpm build 실행
2. 실제 빌드 성공 여부 확인
3. Tailwind 설치 버전 확인
4. CSS의 현재 Tailwind 문법 확인
5. PostCSS plugin 설정 확인
6. VS Code Tailwind CSS IntelliSense 확인
7. 파일 language mode 확인
8. 필요한 경우에만 CSS validation 조정

자주 발생하는 실수

경고만 보고 Tailwind 설치를 다시 합니다

빌드가 정상이라면 의존성 재설치는 문제 해결과 관계없을 수 있습니다.

과거 v3 설정과 현재 설정을 섞습니다

발행 시점 공식 문서를 기준으로 같은 세대의 설치 방식만 사용합니다.

vscode 설정으로 모든 unknownAtRules를 무시합니다

실제 CSS 오타까지 놓칠 수 있습니다.

경고 범위를 이해한 뒤 최소한으로 조정합니다.

TaskFlow 메인 앱에 Tailwind를 강제로 추가합니다

이 과정의 목표는 개발환경 진단입니다.

Tailwind 자체 학습은 Tailwind CSS 과정이 담당합니다.

학습 완료 체크리스트

• Unknown at rule이 실제 빌드 오류인지 에디터 경고인지 구분할 수 있습니다.
• 현재 Tailwind 설치 버전을 확인할 수 있습니다.
• 공식 IntelliSense extension의 역할을 이해했습니다.
• PostCSS plugin 연결 상태를 확인할 수 있습니다.
• 과거 버전 설정을 현재 프로젝트에 섞지 않습니다.
• validation 비활성화를 첫 해결책으로 사용하지 않습니다.

CSS 파일
Vite 개발 서버
PostCSS 개념
VS Code extension

dev-env-step-07-pnpm-recovery

labs/tailwind-at-rule 추가
에디터 경고 재현
빌드 오류 재현
두 문제의 진단 순서 문서화

pnpm dev
pnpm build

dev-env-step-08-tailwind-editor-fix

node_modules/
dist/
storybook-static/
.env.local
.env.*.local

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

import js from '@eslint/js';
import { defineConfig } from 'eslint/config';
import globals from 'globals';

export default defineConfig([
  { ignores: ['dist/**'] },
  js.configs.recommended,
  {
    files: ['src/**/*.js'],
    languageOptions: { globals: globals.browser },
    rules: { 'no-console': 'warn' },
  },
]);

<!doctype html>
<html lang="ko">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TaskFlow 개발환경</title></head>
<body><main id="app"></main><script type="module" src="/src/main.js"></script></body>
</html>

{
  "name": "@taskflow/web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "lint": "eslint ."
  },
  "devDependencies": {
    "vite": "8.3.0",
    "eslint": "10.11.0",
    "@eslint/js": "10.0.1",
    "globals": "17.12.0"
  }
}

const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;

if (!apiUrl) {
  throw new Error('VITE_API_URL 환경 변수가 필요합니다.');
}

export const env = {
  apiUrl,
  appName: appName || 'TaskFlow',
};

import './style.css';
import { env } from './config/env.js';

const app = document.querySelector('#app');
const title = document.createElement('h1');
title.textContent = env.appName;
const status = document.createElement('p');
status.textContent = '개발환경 스타터가 실행 중입니다.';
const api = document.createElement('p');
api.id = 'api-url';
api.textContent = `API URL: ${env.apiUrl}`;
app.append(title, status, api);

body { margin: 0; color: #202020; background: #f6f6f6; font: 16px/1.6 system-ui, sans-serif; }
main { max-width: 720px; margin: 64px auto; padding: 24px; }
h1 { font-size: 30px; font-weight: 500; }
p { overflow-wrap: anywhere; }

# TaskFlow 개발환경

이 스타터는 개발환경 진단을 위한 최소 Vite/vanilla JavaScript 앱입니다. 할 일 관리 기능이나 API 서버는 포함하지 않습니다.

Node.js 24.19.0, pnpm 11.19.0으로 검증했습니다. 루트는 pnpm만 사용하며 apps/*만 workspace입니다. labs의 npm/Yarn/pnpm 실습은 독립 프로젝트입니다.

## 2회차

메인 앱은 pnpm을 유지합니다. labs/yarn-modern은 독립 Yarn 실습입니다.

## 3회차

apps/web/.env.example을 apps/web/.env.local로 복사합니다. .invalid 주소는 표시만 하며 실제 API 호출은 하지 않습니다. 공개 샘플값만 제공하고 로컬 파일은 ZIP에서 제외합니다.

## 4회차

Vite 루트는 apps/web입니다. env.js가 필수 VITE_API_URL을 검사하고 화면에 공개 URL을 표시합니다.

## 5회차

ESLint 설정과 의존성은 apps/web에 있습니다. 루트 pnpm lint가 앱의 eslint .을 호출합니다.

## 6회차

npm ERESOLVE 실습은 labs/npm-eresolve에서 실행합니다. 최종본은 react와 react-dom 19.3.0 호환 조합입니다.

## 7회차

설치 오류는 경로 → Node/pnpm 버전 → workspace → package.json → lockfile 순으로 확인합니다. 새 폴더에서 pnpm install --frozen-lockfile로 재현합니다.

## 8회차

Tailwind lab은 독립 pnpm 프로젝트입니다. PostCSS 빌드와 VS Code 언어 모드/확장 상태를 구분합니다. VS Code GUI 경고는 이번 자동 검증 범위에 포함하지 않았습니다.

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build",
    "lint": "pnpm --filter @taskflow/web lint"
  }
}

packages:
  - "apps/*"

# TaskFlow 개발환경 08 완료 체크포인트

Node.js 24.19.0 / pnpm 11.19.0 검증 기준입니다. pnpm을 별도로 설치한 환경에서 실행하세요. ZIP에는 node_modules, dist, 로컬 환경 변수, 실제 비밀값이 없습니다.

1. 이 폴더에서 `pnpm install --frozen-lockfile`
2. PowerShell: `Copy-Item apps/web/.env.example apps/web/.env.local` 또는 macOS/Linux: `cp apps/web/.env.example apps/web/.env.local`
3. `pnpm dev` 후 http://127.0.0.1:5173 확인
4. `pnpm build`
5. `pnpm lint`

apps/web가 Vite 루트입니다. 환경 변수도 이 폴더에 둡니다. 표시용 API 주소에 실제 요청을 보내지 않습니다. labs는 메인 workspace에서 제외되어 각 폴더에서 별도 설치합니다.

원문 단계별 전체 파일과 실행 검증 범위는 docs/development-environment.md를 확인하세요.

nodeLinker: node-modules

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

console.log('TaskFlow Yarn 독립 실습');

{
  "name": "taskflow-npm-eresolve",
  "private": true,
  "type": "module",
  "packageManager": "npm@11.16.0",
  "scripts": {
    "test": "node verify.mjs"
  },
  "dependencies": {
    "react": "19.3.0",
    "react-dom": "19.3.0"
  }
}

# npm ERESOLVE 실습

이 폴더에서만 npm을 사용합니다.

오류 재현: `npm install react@18.3.1 react-dom@19.3.0 --save-exact`

복구: `npm install react@19.3.0 react-dom@19.3.0 --save-exact`

검증: `npm ls react react-dom`, `npm test`

react-dom 19.3.0의 peerDependencies는 react ^19.3.0입니다. 최종 package.json은 복구된 상태입니다.

import { createElement } from 'react';
import { renderToString } from 'react-dom/server';
import assert from 'node:assert/strict';
const html = renderToString(createElement('p', null, 'TaskFlow'));
assert.equal(html, '<p>TaskFlow</p>');
console.log('React 서버 렌더링 통과');

{
  "recommendations": [
    "bradlc.vscode-tailwindcss"
  ]
}

{
  "files.associations": {
    "*.css": "tailwindcss"
  }
}

<!doctype html>
<html lang="ko"><head><meta charset="UTF-8"><title>Tailwind lab</title><link rel="stylesheet" href="/src/style.css"></head><body><h1 class="text-brand text-2xl">TaskFlow Tailwind</h1></body></html>

{
  "name": "taskflow-tailwind-lab",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@11.19.0",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build"
  },
  "devDependencies": {
    "vite": "8.3.0",
    "tailwindcss": "4.3.3",
    "@tailwindcss/postcss": "4.3.3",
    "postcss": "8.5.28"
  }
}

packages:
  - "."

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

# Tailwind lab

이 폴더에서 `pnpm install --frozen-lockfile`, `pnpm dev`, `pnpm build`를 실행합니다.

빌드 오류 재현은 postcss.config.js의 plugin을 tailwindcss로 바꿔 확인하고, @tailwindcss/postcss로 복구합니다. VS Code에는 Tailwind CSS IntelliSense를 설치하고 이 폴더를 열어 언어 모드를 확인합니다. 전역 CSS 검사는 끄지 않습니다.

@import "tailwindcss";

@theme {
  --color-brand: #111111;
}

다음 학습

다음 글에서는 Storybook과 Vite에서 동적 import 모듈을 가져오지 못할 때 브라우저 네트워크 요청과 import 경로부터 확인합니다.

다음 글: Storybook Failed to fetch dynamically imported module 해결 (Vite)

공식 문서

• Tailwind Editor setup: https://tailwindcss.com/docs/editor-setup
• Tailwind PostCSS installation: https://tailwindcss.com/docs/installation/using-postcss