Extracting

UnoCSS는 코드베이스에서 유틸리티 사용을 검색하고 온디맨드로 해당 CSS를 생성하여 작동합니다. 이 과정을 extracting이라고 부릅니다.

콘텐츠 소스

UnoCSS는 여러 소스에서 유틸리티 사용을 추출하는 것을 지원합니다:

• Pipeline - 빌드 도구 파이프라인에서 직접 추출
• Filesystem - 파일을 읽고 감시하여 파일시스템에서 추출
• Inline - 인라인 일반 텍스트에서 추출

다른 소스에서 나오는 유틸리티 사용은 병합되어 최종 CSS를 생성합니다.

빌드 도구 파이프라인에서 추출

이는 Vite 및 Webpack 통합에서 지원됩니다.

UnoCSS는 빌드 도구 파이프라인을 통과하는 콘텐츠를 읽고 그곳에서 유틸리티 사용을 추출합니다. 이는 추출 중에 추가 파일 I/O가 없이 앱에서 실제로 사용되는 사용만 스마트하게 추출하므로 가장 효율적이고 정확한 추출 방법입니다.

기본적으로 UnoCSS는 빌드 파이프라인의 .jsx, .tsx, .vue, .md, .html, .svelte, .astro 확장자를 가진 파일에서 유틸리티 사용을 추출한 다음 온디맨드로 적절한 CSS를 생성합니다. .js 및 .ts 파일은 기본적으로 포함되지 않습니다.

이를 구성하려면 uno.config.ts를 업데이트할 수 있습니다:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // the default
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // include js/ts files
        'src/**/*.{js,ts}',
      ],
      // exclude files
      // exclude: []
    },
  },
})

또한 파일 기반으로 @unocss-include 마법 주석을 UnoCSS가 스캔하기를 원하는 파일의 어디든 추가할 수 있습니다. *.js 또는 *.ts 파일을 스캔해야 한다면, 구성에 추가하여 모든 js/ts 파일을 스캔 대상으로 포함하세요.

// ./some-utils.js

// since `.js` files are not included by default,
// the following comment tells UnoCSS to force scan this file.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

마찬가지로, 전체 파일의 스캔 및 변환을 우회하기 위해 @unocss-ignore를 추가할 수도 있습니다.

UnoCSS가 추출 파일에서 추출되지 않고 코드 블록을 건너뛰게 하려면 @unocss-skip-start @unocss-skip-end를 쌍으로 사용할 수 있습니다. 효과적이려면 쌍으로 사용해야 합니다.

<p class="text-green text-xl">Green Large</p>

<!-- @unocss-skip-start -->
<!-- `text-red` will not be extracted -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

파일시스템에서 추출

빌드 도구 파이프라인에 접근할 수 없는 통합(예: PostCSS 플러그인)을 사용하거나, 코드가 파이프라인을 통과하지 않는 백엔드 프레임워크와 통합하는 경우, 추출할 파일을 수동으로 지정할 수 있습니다.

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

일치하는 파일은 파일시스템에서 직접 읽히고 개발 모드에서 변경사항이 감시됩니다.

인라인 텍스트에서 추출

또한 다른 곳에서 검색할 수 있는 인라인 텍스트에서 유틸리티 사용을 추출할 수도 있습니다.

콘텐츠를 반환하는 비동기 함수를 전달할 수도 있습니다. 하지만 함수는 빌드 시에만 한 번 호출됩니다.

export default defineConfig({
  content: {
    inline: [
      // plain text
      '<div class="p-4 text-red">Some text</div>',
      // async getter
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

제한사항

UnoCSS는 빌드 시에 작동하므로, 정적으로 제시된 유틸리티만 생성되어 앱에 제공됩니다. 동적으로 사용되거나 런타임에 외부 리소스에서 가져오는 유틸리티는 감지되거나 적용되지 않을 수 있습니다.

Safelist

때로는 다음과 같은 동적 연결을 사용하고 싶을 수 있습니다:

<div class="p-${size}"></div>
<!-- this won't work! -->

UnoCSS가 정적 추출을 사용하여 빌드 시에 작동한다는 사실로 인해, 컴파일 시에는 모든 유틸리티 조합을 알 수 없습니다. 이를 위해 safelist 옵션을 구성할 수 있습니다.

safelist: 'p-1 p-2 p-3 p-4'.split(' ')

해당하는 CSS가 항상 생성됩니다:

.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }

또는 더 유연하게:

safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

런타임에 진정한 동적 생성을 원한다면 @unocss/runtime 패키지를 확인해보세요.

정적 목록 조합

동적으로 구성된 유틸리티의 제한을 우회하는 또 다른 방법은 모든 조합을 정적으로 나열하는 객체를 사용하는 것입니다. 예를 들어, 이것을 원한다면:

<div class="text-${color} border-${color}"></div>
<!-- this won't work! -->

모든 조합을 나열하는 객체를 만들 수 있습니다 (사용하려는 color의 가능한 모든 값을 알고 있다고 가정)

// Since they are static, UnoCSS will able to extract them on build time
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

그리고 템플릿에서 사용합니다:

<div class="${classes[color]}"></div>

Blocklist

safelist와 유사하게, blocklist를 구성하여 일부 유틸리티가 생성되지 않도록 제외할 수도 있습니다. 이는 일부 추출 오탐을 제외하는 데 유용합니다. safelist와 달리 blocklist는 정확한 매치를 위한 문자열과 패턴 매치를 위한 정규식을 모두 받습니다.

blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

이것은 p-1과 p-2, p-3, p-4가 생성되지 않도록 제외합니다.