가져오기 및 가상 모듈

Markdown으로 보기 GitHub에서 수정 문서 위치 3843abd

TailwindPHP은 컴파일 전에 @import 규칙을 확인합니다. 가져오기는 내장 가상 모듈(tailwindcss 등), importPaths 옵션을 통한 디스크의 파일, 또는 사용자 지정 리졸버가 반환하는 모든 항목을 가리킬 수 있습니다.

가상 모듈

@import "tailwindcss"은 대부분의 프로젝트에서 사용하는 진입점입니다. 아래 네 줄로 확장됩니다. 레이어 순서 선언과 각 캐스케이드 레이어에 할당된 세 개의 하위 가져오기입니다:

CSS

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

각 하위 가져오기도 개별적으로 가져올 수 있는 가상 모듈입니다. 사용 가능한 가상 모듈은 다음과 같습니다:

모듈	내용
`tailwindcss`	전체 번들: 테마 + Preflight + 유틸리티.
`tailwindcss/theme.css`	테마 변수만(색상, 간격 기본값, 중단점 등).
`tailwindcss/preflight.css`	Preflight 기본 초기화.
`tailwindcss/utilities.css`	유틸리티 레이어.
`tw-animate-css`	`tw-animate-css` 애니메이션 유틸리티.

각 부분을 개별적으로 가져오면 Preflight를 생략하거나 레이어 순서를 바꿀 수 있습니다(아래 참조).

tw-animate-css 애니메이션

tw-animate-css는 TailwindCSS v4 애니메이션 라이브러리로, tailwindcss-animate를 바로 대체할 수 있습니다. 내장 가상 모듈로 제공되므로 유틸리티 레이어와 함께 가져오면 진입 및 종료 애니메이션 클래스도 다른 유틸리티처럼 컴파일됩니다:

CSS

@import "tw-animate-css";
@import "tailwindcss/utilities.css";

애니메이션 유틸리티는 다음을 지원합니다:

진입 / 종료 — animate-in, animate-out
페이드 — fade-in, fade-out
확대/축소 — zoom-in, zoom-out
회전 — spin-in, spin-out
흐림 — blur-in, blur-out
슬라이드 — slide-in-from-top / -bottom / -left / -right 및 이에 대응하는 slide-out-to-*, RTL을 지원하는 -start / -end
타이밍 — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate, fill-mode-none / -forwards / -backwards / -both
재생 상태 — running, paused
컴포넌트 애니메이션 — accordion-down / accordion-up, collapsible-down / collapsible-up, caret-blink

이 클래스는 다른 유틸리티처럼 Tailwind 변형과 조합되므로 shadcn/ui 대화상자 및 드롭다운 패턴에 바로 사용할 수 있습니다.

`importPaths` 옵션

파일 시스템에서 @import를 확인하려면 generate() 배열 형식에 importPaths을 전달하세요. 단일 경로, 디렉터리 또는 둘 중 하나의 배열을 받습니다.

PHP

use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);

중첩 가져오기

불러온 파일 안의 가져오기는 해당 파일을 기준으로 확인합니다. /path/to/styles.css에 @import "./components/buttons.css"이 있으면 경로는 /path/to/를 기준으로 확인됩니다:

CSS

/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

@theme {
    --color-brand: #3b82f6;
}

중복 제거

같은 파일이나 가상 모듈을 두 번 이상 가져오면 첫 번째 이후 호출은 아무 작업도 하지 않습니다. 반복되는 @import "tailwindcss" 줄이나 같은 부분 파일을 가져오는 두 파일은 자동으로 중복 제거됩니다. 순환 가져오기도 방지합니다.

사용자 지정 리졸버

가상 파일 시스템, 데이터베이스 또는 파일 시스템이 아닌 소스의 경우 importPaths로 호출 가능한 함수를 전달하세요. 이 함수는 가져오기 URI와 가져오기를 확인할 기준 디렉터리를 받고, CSS 또는 null를 반환합니다:

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);

$uri이 null일 때(null도 두 번째 인수로 전달되는 첫 호출) 진입 CSS을 반환하세요. 다른 URI의 경우 해당 CSS 콘텐츠를 반환하거나 null를 반환해 파일 시스템 검색으로 대체할 수 있습니다. 찾는 항목이 없으면 가져오기를 조용히 건너뜁니다.

사전 점검

Preflight는 modern-normalize를 기반으로 한 Tailwind의 기본 초기화입니다. 브라우저 간 차이를 줄여 유틸리티가 일관되게 동작하도록 합니다. 기본 여백을 제거하고 제목과 목록의 기본 스타일을 없애며, 이미지를 블록 요소로 만들고, 테두리 스타일을 초기화해 border-width만으로 테두리를 그릴 수 있게 하고, 버튼이 글꼴을 상속하도록 하는 등의 작업을 수행합니다.

Preflight는 @import "tailwindcss"에 포함되어 있으므로 전체 번들을 가져오면 이미 사용할 수 있습니다:

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);

Preflight 확장하기

@layer base으로 Preflight 위에 자체 기본 스타일을 추가하세요:

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);

Preflight 비활성화하기

기존 프로젝트에 통합할 때는 필요한 부분만 가져오고 Preflight 줄은 생략하세요:

PHP

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);

가져오기 수정자

Tailwind의 파일을 개별적으로 가져올 때는 영향을 받는 가져오기에 수정자를 추가하세요:

CSS

/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);

참조 가져오기

@import "…" reference은 정의만 불러옵니다. @theme 값, 파일 안에 정의된 @utility 및 @custom-variant을 사용할 수 있지만, 해당 파일에서는 자체 CSS가 출력되지 않습니다. 파일 내용을 @media reference { … }로 감싸는 것과 같으며, 직접 다음과 같이 작성할 수도 있습니다:

CSS

@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}

bg-brand은 background-color: var(--color-brand, #f00);로 컴파일되며 --color-brand 선언은 출력되지 않습니다.

현재 릴리스에는 다음과 같은 제한 사항이 두 가지 있습니다(#14):

참조 가져오기와 @media reference 블록은 tailwindcss 또는 tailwindcss/utilities.css의 @import 뒤에 두세요. 앞에 배치하면 전체 출력이 비어 있게 됩니다.
내장 가상 모듈(@import "tailwindcss" reference;)의 reference은 아직 효과가 없습니다. 테마, Preflight, 유틸리티가 계속 출력됩니다.

테마 변수는 Theme에서, 클래스 이름을 스캔할 파일을 제어하려면 @source에서 계속 확인하세요.