# 가져오기 및 가상 모듈
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](https://github.com/Wombosvideo/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' => 'Hello
',
'importPaths' => '/path/to/styles.css',
]);
// Directory (loads all .css files alphabetically)
$css = tw::generate([
'content' => 'Hello
',
'importPaths' => '/path/to/css/',
]);
// Multiple paths — files and directories
$css = tw::generate([
'content' => 'Hello
',
'importPaths' => [
'/path/to/base.css',
'/path/to/components/',
],
]);
// Combine with inline css
$css = tw::generate([
'content' => 'Hello
',
'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' => 'Hello
',
'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](https://github.com/sindresorhus/modern-normalize)를 기반으로 한 Tailwind의 기본 초기화입니다. 브라우저 간 차이를 줄여 유틸리티가 일관되게 동작하도록 합니다. 기본 여백을 제거하고 제목과 목록의 기본 스타일을 없애며, 이미지를 블록 요소로 만들고, 테두리 스타일을 초기화해 `border-width`만으로 테두리를 그릴 수 있게 하고, 버튼이 글꼴을 상속하도록 하는 등의 작업을 수행합니다.
Preflight는 `@import "tailwindcss"`에 포함되어 있으므로 전체 번들을 가져오면 이미 사용할 수 있습니다:
```php
use TailwindPHP\tw;
$css = tw::generate([
'content' => 'Hello
',
'css' => '@import "tailwindcss";',
]);
```
### Preflight 확장하기
`@layer base`으로 Preflight 위에 자체 기본 스타일을 추가하세요:
```php
use TailwindPHP\tw;
$css = tw::generate([
'content' => 'Title
Content
',
'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' => 'Hello
',
'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](https://github.com/inline0/tailwindphp/issues/14)):
- 참조 가져오기와 `@media reference` 블록은 `tailwindcss` 또는 `tailwindcss/utilities.css`의 `@import` 뒤에 두세요. 앞에 배치하면 전체 출력이 비어 있게 됩니다.
- 내장 가상 모듈(`@import "tailwindcss" reference;`)의 `reference`은 아직 효과가 없습니다. 테마, Preflight, 유틸리티가 계속 출력됩니다.
테마 변수는 [Theme](https://tailwindphp.inline0.dev/ko/docs/usage/theme)에서, 클래스 이름을 스캔할 파일을 제어하려면 [@source](https://tailwindphp.inline0.dev/ko/docs/usage/source)에서 계속 확인하세요.