Configuration

Tailwind는 맞춤형 사용자 인터페이스를 구축하기 위한 프레임워크로, 처음부터 커스터마이징을 염두에 두고 설계되었습니다.

기본적으로 Tailwind는 프로젝트 루트에 있는 tailwind.config.js 파일을 찾습니다. 이 파일에서 여러분은 원하는 커스터마이징을 정의할 수 있습니다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  },
}

설정 파일의 모든 섹션은 선택 사항이므로, 변경하고 싶은 부분만 지정하면 됩니다. 누락된 섹션은 Tailwind의 기본 설정으로 대체됩니다.

​설정 파일 만들기

tailwindcss npm 패키지를 설치할 때 포함된 Tailwind CLI 유틸리티를 사용해 프로젝트의 Tailwind 설정 파일을 생성할 수 있습니다:

npx tailwindcss init

이 명령어를 실행하면 프로젝트 루트에 최소한의 tailwind.config.js 파일이 생성됩니다:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

​다른 파일 이름 사용하기

tailwind.config.js 이외의 이름을 사용하려면 커맨드라인에서 인자로 전달하면 됩니다.

npx tailwindcss init tailwindcss-config.js

커스텀 파일 이름을 사용할 경우, Tailwind CLI 도구로 CSS를 컴파일할 때 커맨드라인 인자로 지정해야 합니다.

npx tailwindcss -c ./tailwindcss-config.js -i input.css -o output.css

Tailwind를 PostCSS 플러그인으로 사용하는 경우, PostCSS 설정에서 커스텀 설정 파일 경로를 지정해야 합니다.

module.exports = {
  plugins: {
    tailwindcss: { config: './tailwindcss-config.js' },
  },
}

또는 @config 지시자를 사용해 커스텀 설정 파일 경로를 지정할 수도 있습니다.

@config "./tailwindcss-config.js";

@tailwind base;
@tailwind components;
@tailwind utilities;

@config 지시자에 대해 더 알아보려면 함수와 지시문 문서를 참고하세요.

​ESM 또는 TypeScript 사용하기

Tailwind CSS를 ESM(ECMAScript Modules)이나 TypeScript로도 설정할 수 있습니다:

/** @type {import('tailwindcss').Config} */
export default {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

npx tailwindcss init 명령어를 실행하면, 프로젝트가 ES 모듈인지 자동으로 감지하고 적절한 구문으로 설정 파일을 생성합니다.

또한 --esm 플래그를 사용해 명시적으로 ESM 설정 파일을 생성할 수도 있습니다:

npx tailwindcss init --esm

TypeScript 설정 파일을 생성하려면 --ts 플래그를 사용하세요:

npx tailwindcss init --ts

​PostCSS 설정 파일 생성하기

tailwind.config.js 파일과 함께 기본적인 postcss.config.js 파일도 생성하려면 -p 플래그를 사용하세요:

npx tailwindcss init -p

이 명령어를 실행하면 프로젝트에 다음과 같은 postcss.config.js 파일이 생성됩니다:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

​전체 기본 설정 스캐폴딩

대부분의 사용자에게는 설정 파일을 최소한으로 유지하고, 커스텀하고 싶은 부분만 지정하는 것을 권장합니다.

만약 Tailwind의 모든 기본 설정을 포함한 완전한 설정 파일을 스캐폴딩하고 싶다면, --full 옵션을 사용하세요:

npx tailwindcss init --full

이 명령어를 실행하면 Tailwind가 내부적으로 사용하는 기본 설정 파일과 동일한 파일을 얻을 수 있습니다.

​Configuration options

​Content

content 섹션은 Tailwind 클래스 이름이 포함된 모든 HTML 템플릿, JS 컴포넌트 및 기타 파일의 경로를 설정하는 곳입니다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{html,js}',
    './components/**/*.{html,js}',
  ],
  // ...
}

콘텐츠 소스 설정에 대해 더 알아보려면 콘텐츠 설정 문서를 참고하세요.

​Theme

theme 섹션은 사이트의 시각적 디자인과 관련된 색상 팔레트, 폰트, 글꼴 크기, 테두리 크기, 브레이크포인트 등을 정의하는 곳입니다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  theme: {
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

기본 테마와 이를 커스터마이징하는 방법에 대해 더 알아보려면 테마 설정 가이드를 참고하세요.

​플러그인

plugins 섹션을 사용하면 Tailwind에 플러그인을 등록할 수 있습니다. 이 플러그인들은 추가 유틸리티, 컴포넌트, 기본 스타일, 또는 커스텀 변형을 생성하는 데 사용될 수 있습니다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/typography'),
    require('tailwindcss-children'),
  ],
}

자신만의 플러그인을 작성하는 방법에 대해 더 알아보려면 플러그인 작성 가이드를 참고하세요.

​프리셋

presets 섹션을 사용하면 Tailwind의 기본 설정 대신 여러분만의 커스텀 기본 설정을 지정할 수 있습니다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  presets: [
    require('@acmecorp/base-tailwind-config')
  ],

  // 프로젝트별 커스터마이징
  theme: {
    //...
  },
}

프리셋에 대해 더 자세히 알아보려면 프리셋 문서를 참고하세요.

​Prefix

prefix 옵션을 사용하면 Tailwind에서 생성된 모든 유틸리티 클래스에 커스텀 접두사를 추가할 수 있습니다. 이는 기존 CSS 위에 Tailwind를 적용할 때 이름 충돌이 발생할 수 있는 상황에서 매우 유용합니다.

예를 들어, tw- 접두사를 추가하려면 다음과 같이 prefix 옵션을 설정할 수 있습니다:

/** @type {import('tailwindcss').Config} */
module.exports = {
  prefix: 'tw-',
}

이제 모든 클래스는 설정된 접두사와 함께 생성됩니다:

.tw-text-left {
  text-align: left;
}
.tw-text-center {
  text-align: center;
}
.tw-text-right {
  text-align: right;
}
/* etc. */

이 접두사는 모든 변형 수정자(variant modifiers) 이후에 추가된다는 점을 이해하는 것이 중요합니다. 즉, sm: 또는 hover:와 같은 반응형 또는 상태 수정자가 있는 클래스는 여전히 반응형 또는 상태 수정자가 먼저 오고, 그 뒤에 커스텀 접두사가 붙습니다:

<div class="tw-text-lg md:tw-text-xl tw-bg-red-500 hover:tw-bg-blue-500">
  <!-- -->
</div>

음수 값을 나타내는 대시 수정자는 접두사 앞에 추가됩니다. 따라서 -mt-8은 tw-를 접두사로 설정한 경우 -tw-mt-8이 됩니다:

<div class="-tw-mt-8">
  <!-- -->
</div>

접두사는 Tailwind에서 생성된 클래스에만 추가됩니다. 여러분이 직접 정의한 커스텀 클래스에는 접두사가 추가되지 않습니다.

즉, 다음과 같이 커스텀 유틸리티를 추가하면:

@layer utilities {
  .bg-brand-gradient { /* ... */ }
}

생성된 변형 클래스에는 설정한 접두사가 붙지 않습니다:

.bg-brand-gradient { /* ... */ }
.hover\:bg-brand-gradient:hover { /* ... */ }

커스텀 유틸리티에도 접두사를 추가하려면 클래스 정의에 접두사를 직접 추가하면 됩니다:

@layer utilities {
  .tw-bg-brand-gradient { /* ... */ }
}

​Important

important 옵션은 Tailwind의 유틸리티 클래스에 !important를 추가할지 여부를 제어합니다. 이 기능은 높은 우선순위 점수를 가진 기존 CSS와 Tailwind를 함께 사용할 때 매우 유용합니다.

유틸리티 클래스를 !important로 생성하려면 설정 파일에서 important 키를 true로 설정합니다:

/** @type {import('tailwindcss').Config} */
module.exports = {
  important: true,
}

이제 모든 Tailwind 유틸리티 클래스가 !important로 생성됩니다:

.leading-none {
  line-height: 1 !important;
}
.leading-tight {
  line-height: 1.25 !important;
}
.leading-snug {
  line-height: 1.375 !important;
}
/* etc. */

이 설정은 @layer utilities 지시어를 사용해 정의한 커스텀 유틸리티에도 적용됩니다:

/* Input */
@layer utilities {
  .bg-brand-gradient {
    background-image: linear-gradient(#3490dc, #6574cd);
  }
}

/* Output */
.bg-brand-gradient {
  background-image: linear-gradient(#3490dc, #6574cd) !important;
}

​선택자 전략

important를 true로 설정하면, 엘리먼트에 인라인 스타일을 추가하는 서드파티 JS 라이브러리를 사용할 때 문제가 발생할 수 있습니다. 이 경우, Tailwind의 !important 유틸리티가 인라인 스타일을 무시하게 되어 의도한 디자인이 깨질 수 있습니다.

이 문제를 해결하기 위해 important를 #app과 같은 ID 선택자로 설정할 수 있습니다:

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  important: '#app',
}

이 설정은 모든 유틸리티에 주어진 선택자를 접두사로 추가하여, 실제로 !important를 사용하지 않으면서도 명시도를 높입니다.

important 선택자를 지정한 후에는 사이트의 루트 엘리먼트가 이 선택자와 일치하는지 확인해야 합니다. 위 예제를 사용한다면, 스타일이 제대로 작동하려면 루트 엘리먼트의 id 속성을 app으로 설정해야 합니다.

설정이 완료되고 루트 엘리먼트가 Tailwind 설정의 선택자와 일치하면, Tailwind의 모든 유틸리티는 프로젝트에서 사용된 다른 클래스를 무시할 만큼 충분히 높은 명시도를 가지게 되며, 인라인 스타일을 방해하지 않습니다:

<html>
<!-- ... -->
<style>
  .high-specificity .nested .selector {
    color: blue;
  }
</style>
<body id="app">
  <div class="high-specificity">
    <div class="nested">
      <!-- 빨간색으로 표시됨 -->
      <div class="selector text-red-500"><!-- ... --></div>
    </div>
  </div>

  <!-- #bada55 색상으로 표시됨 -->
  <div class="text-red-500" style="color: #bada55;"><!-- ... --></div>
</body>
</html>

선택자 전략을 사용할 때는, 루트 선택자를 포함하는 템플릿 파일이 콘텐츠 설정에 포함되어 있는지 확인해야 합니다. 그렇지 않으면 프로덕션 빌드 시 모든 CSS가 제거될 수 있습니다.

​Important modifier

대안으로, 유틸리티 앞에 ! 문자를 추가하여 중요하게 만들 수 있습니다:

<p class="!font-medium font-bold">
  이 텍스트는 bold가 CSS에서 나중에 오더라도 medium으로 표시됩니다.
</p>

!는 항상 유틸리티 이름의 맨 앞에 위치하며, 모든 변형 뒤에 오지만 접두사 앞에 옵니다:

<div class="sm:hover:!tw-font-bold">

이 방법은 여러분이 제어할 수 없는 스타일과 충돌할 때 우선순위 점수를 높여야 하는 드문 상황에서 유용할 수 있습니다.

​Separator

separator 옵션을 사용하면 수정자(화면 크기, hover, focus 등)와 유틸리티 이름(text-center, items-end 등)을 구분하는 데 사용할 문자를 커스터마이징할 수 있습니다.

기본적으로 콜론(:)을 사용하지만, Pug와 같은 템플릿 언어를 사용할 때 클래스 이름에 특수 문자를 지원하지 않는 경우 이 설정을 변경하는 것이 유용할 수 있습니다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  separator: '_',
}

​코어 플러그인

corePlugins 섹션은 프로젝트에서 필요하지 않은 경우 Tailwind가 기본적으로 생성하는 클래스를 완전히 비활성화할 수 있게 해줍니다.

특정 코어 플러그인을 비활성화하려면, corePlugins에 해당 플러그인을 false로 설정한 객체를 제공하세요:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: {
    float: false,
    objectFit: false,
    objectPosition: false,
  }
}

활성화할 코어 플러그인을 지정하고 싶다면, 사용할 코어 플러그인 목록을 포함한 배열을 제공하세요:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: [
    'margin',
    'padding',
    'backgroundColor',
    // ...
  ]
}

Tailwind의 모든 코어 플러그인을 비활성화하고 커스텀 플러그인만 사용하고 싶다면, 빈 배열을 제공하세요:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: []
}

참고용으로 모든 코어 플러그인 목록은 다음과 같습니다:

​여러 설정 사용하기

서로 다른 Tailwind 설정을 사용하여 여러 CSS 파일을 생성해야 하는 프로젝트의 경우, @config 지시자를 사용하여 각 CSS 진입점에 사용할 설정 파일을 지정할 수 있습니다:

@config "./tailwind.site.config.js";

@tailwind base;
@tailwind components;
@tailwind utilities;

@config 지시자에 대해 더 자세히 알아보려면 함수 & 지시자 문서를 참고하세요.

​JavaScript에서 참조하기

클라이언트 측 JavaScript에서 설정 값을 참조하는 것은 종종 유용합니다. 예를 들어, React나 Vue 컴포넌트에서 동적으로 인라인 스타일을 적용할 때 테마 값을 접근해야 할 때가 있습니다.

이를 쉽게 하기 위해, Tailwind는 resolveConfig 헬퍼를 제공합니다. 이 헬퍼를 사용하면 설정 객체의 완전히 병합된 버전을 생성할 수 있습니다.

import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from './tailwind.config.js'

const fullConfig = resolveConfig(tailwindConfig)

fullConfig.theme.width[4]
// => '1rem'

fullConfig.theme.screens.md
// => '768px'

fullConfig.theme.boxShadow['2xl']
// => '0 25px 50px -12px rgba(0, 0, 0, 0.25)'

이 방법은 빌드 시점의 많은 의존성을 포함하게 되므로, 클라이언트 측 번들 크기가 커질 수 있습니다. 이를 방지하기 위해, babel-plugin-preval과 같은 도구를 사용하여 빌드 시점에 설정의 정적 버전을 생성하는 것을 권장합니다.

​TypeScript 타입

Tailwind는 tailwind.config.js 파일을 위한 퍼스트파티 TypeScript 타입을 제공합니다. 이를 통해 다양한 유용한 IDE 지원을 받을 수 있으며, 문서를 자주 참조하지 않고도 설정을 변경하기가 훨씬 쉬워집니다.

Tailwind CLI로 생성된 설정 파일은 기본적으로 필요한 타입 주석을 포함하고 있습니다. 하지만 TypeScript 타입을 수동으로 설정하려면, 설정 객체 위에 타입 주석을 추가하면 됩니다:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}