@astrojs/ tailwind

이 Astro 통합 은 Tailwind 구성 파일에 대한 지원과 함께 프로젝트의 모든 .astro 파일 및 프레임워크 컴포넌트에 Tailwind의 유틸리티 CSS 클래스를 제공합니다.

왜 Tailwind인가?

Tailwind를 사용하면 CSS를 작성하는 대신 유틸리티 클래스를 사용할 수 있습니다. 이러한 유틸리티 클래스는 대부분 특정 CSS 속성 설정과 일대일입니다. 예를 들어 요소에 text-lg를 추가하는 것은 CSS에서 font-size: 1.125rem을 설정하는 것과 같습니다. 미리 정의된 유틸리티 클래스를 사용하면 스타일을 작성하고 유지하는 것이 더 쉬울 수도 있습니다!

사전 정의된 설정이 마음에 들지 않으면 프로젝트의 디자인 요구 사항에 맞게 Tailwind 구성 파일을 맞춤설정할 수 있습니다. 예를 들어 디자인의 “큰 텍스트”가 실제로 2rem인 경우 lg 글꼴 크기 설정을 2rem으로 변경할 수 있습니다.

Tailwind는 컴포넌트 파일에서 <style> 태그를 지원하지 않는 React, Preact, Solid 컴포넌트에 스타일을 추가하는 데에도 좋은 선택입니다.

참고: 동일한 파일에서 Tailwind와 다른 스타일 지정 방법 (예: Styled Components)을 모두 사용하는 것은 일반적으로 권장되지 않습니다.

설치

Astro에는 공식 통합 설정을 자동화하는 astro add 명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.

새 터미널 창에서 다음 명령 중 하나를 실행합니다.

npx astro add tailwind

pnpm astro add tailwind

yarn astro add tailwind

문제가 발생하면 GitHub에서 언제든지 보고하고 아래 수동 설치 단계를 시도해 보세요.

수동 설치

먼저 패키지 관리자를 사용하여 @astrojs/tailwind 및 tailwindcss 패키지를 설치합니다.

npm install @astrojs/tailwind tailwindcss

pnpm add @astrojs/tailwind tailwindcss

yarn add @astrojs/tailwind tailwindcss

그런 다음 integrations 속성을 사용하여 Astro 구성 파일에 통합을 적용합니다.

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [tailwind()],
});

그런 다음 프로젝트의 루트 디렉터리에 tailwind.config.mjs 파일을 만듭니다. 다음 명령을 사용하여 기본 구성 파일을 생성할 수 있습니다.

npx tailwindcss init

pnpm dlx tailwindcss init

yarn dlx tailwindcss init

마지막으로 tailwind.config.mjs 파일에 다음 기본 구성을 추가하세요.

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

사용하기

통합을 설치하면 Tailwind의 유틸리티 클래스를 즉시 사용할 수 있습니다. Tailwind 사용 방법을 알아보려면 Tailwind 문서로 이동하세요. 사용해보고 싶은 유틸리티 클래스가 있으면 프로젝트의 HTML 요소에 추가하세요!

Autoprefixer 역시 개발 모드와 프로덕션 빌드에서 자동으로 설정되므로 Tailwind 클래스는 이전 브라우저에서 작동합니다.

구성

Tailwind 구성

빠른 설치 지침을 사용하고 각 프롬프트에 yes라고 답한 경우 프로젝트의 루트 디렉터리에 tailwind.config.mjs 파일이 표시됩니다. Tailwind 구성 변경에 이 파일을 사용하세요. Tailwind 문서에서 이 파일을 사용하여 Tailwind를 맞춤설정하는 방법을 알아볼 수 있습니다.

없는 경우 자체 tailwind.config.(js|cjs|mjs|ts|mts|cts) 파일을 루트 디렉터리에 추가하면 통합에서 해당 구성을 사용합니다. 이미 다른 프로젝트에 Tailwind를 구성했고 해당 설정을 이 프로젝트로 가져오려는 경우 유용할 수 있습니다.

통합 구성

Astro Tailwind 통합은 Astro와 Tailwind 간 통신을 처리하며 자체 옵션이 있습니다. 프로젝트의 통합 설정이 있는 astro.config.mjs 파일 (Tailwind 구성 파일이 아님)에서 이를 변경하세요.

구성 파일

이전에는 @astrojs/tailwind v3에서 config.path로 알려졌습니다. 구성을 업데이트하려면 v4 변경 로그를 참조하세요.

기본 tailwind.config.(js|cjs|mjs|ts|mts|cts) 대신 다른 Tailwind 구성 파일을 사용하려면 이 통합의 configFile 옵션을 사용하여 해당 파일의 위치를 지정하세요. configFile이 상대적인 경우 현재 작업 디렉터리를 기준으로 탐색합니다.

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 예: Tailwind 구성 파일에 대한 맞춤 경로 제공
      configFile: './custom-config.mjs',
    }),
  ],
});

applyBaseStyles

이전에는 @astrojs/tailwind v3에서 config.applyBaseStyles로 알려졌습니다. 구성을 업데이트하려면 v4 변경 로그를 참조하세요.

기본적으로 통합은 프로젝트의 모든 페이지에서 기본 base.css 파일을 가져옵니다. 이 기본 CSS 파일에는 세 가지 주요 @tailwind 지시어가 포함되어 있습니다.

/* 통합의 기본 삽입된 base.css 파일 */
@tailwind base;
@tailwind components;
@tailwind utilities;

이 기본 동작을 비활성화하려면 applyBaseStyles를 false로 설정하세요. 이는 자신만의 base.css 파일을 정의해야 하는 경우 (예를 들어 @layer 지시어를 포함하기 위해) 유용할 수 있습니다. 프로젝트의 모든 페이지에서 base.css를 가져오지 않으려는 경우에도 유용할 수 있습니다.

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 예: 모든 페이지에 기본 `base.css` 가져오기를 삽입하는 것을 비활성화합니다.
      // 사용자 정의 `base.css`를 정의 및/또는 가져와야 하는 경우 유용합니다.
      applyBaseStyles: false,
    }),
  ],
});

이제 여러분의 base.css를 로컬 스타일시트로 가져올 수 있습니다.

nesting

Tailwind의 구문과 함께 중첩된 CSS 선언을 작성할 수 있도록 tailwindcss/nesting PostCSS 플러그인을 적용하려면 true로 설정하세요. 이 옵션은 기본적으로 false입니다.

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [
    tailwind({
      // 예: Tailwind 구문과 함께 중첩된 CSS 선언 작성 허용
      nesting: true,
    }),
  ],
});

예시

Astro Tailwind Starter를 사용하면 Tailwind를 사용하여 스타일링하는 프로젝트의 기반을 마련하고 실행할 수 있습니다.
Astro의 홈페이지는 Tailwind를 사용합니다. Tailwind 구성 파일 또는 예시 컴포넌트를 확인하세요.
Astro Ink, Sarissa Blog, Astro Tech Blog, Creek 테마는 스타일링에 Tailwind를 사용합니다.
더 많은 예시를 보려면 GitHub에서 Astro Tailwind 프로젝트를 찾아보세요!

문제 해결

`@apply` 지시어가 포함된 클래스가 존재하지 않습니다.

Astro, Vue, Svelte 또는 다른 컴포넌트 통합의 <style> 태그에서 @apply 지시어를 사용하면 사용자 정의 Tailwind 클래스가 존재하지 않는다는 오류가 생성되어 빌드가 실패할 수 있습니다.

error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.

전역 스타일시트에서 @layer 지시어를 사용하는 대신 Tailwind 구성에 플러그인을 추가하여 맞춤 스타일을 정의하여 문제를 해결하세요.

export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};

클래스 기반 수정자는 `@apply` 지시어와 함께 작동하지 않습니다.

수정자가 있는 특정 Tailwind 클래스는 여러 요소의 클래스 결합에 의존합니다. 예를 들어 group-hover:text-gray는 .group:hover .text-gray로 컴파일됩니다. Astro <style> 태그의 @apply 지시어와 함께 사용되면 컴파일된 스타일이 .astro 파일의 어떤 마크업과도 일치하지 않기 때문에 빌드 출력에서 제거됩니다. Vue 및 Svelte와 같은 범위 지정 스타일을 지원하는 프레임워크 컴포넌트에서도 동일한 문제가 발생할 수 있습니다.

이 문제를 해결하려면 대신 인라인 클래스를 사용할 수 있습니다.

<p class="text-black group-hover:text-gray">Astro</p>

기타 문제

설치가 작동하지 않는 것 같으면 개발 서버를 다시 시작해 보세요.
파일을 편집하고 저장했는데 사이트 업데이트가 제대로 표시되지 않으면 페이지를 새로 고쳐보세요.
페이지를 새로 고쳐도 미리보기가 업데이트되지 않거나 새로 설치해도 작동하지 않는 것 같으면 개발 서버를 다시 시작하세요.

도움이 필요하시면 Discord의 #support 채널을 확인하세요. 우리의 친절한 지원팀 멤버들이 도와드리겠습니다!

통합에 대한 자세한 내용은 Astro 통합 문서를 확인하실 수도 있습니다.