Safelist

Safelistは、UnoCSSの設定において重要なオプションであり、ソースコードでこれらのクラスが検出されるかどうかに関わらず、生成されるCSSに常に含めるべきユーティリティクラスのセットを指定することができます。

基本的な使い方

文字列配列

最も簡単な使い方は、保持したいクラス名を含む文字列配列を提供することです：

// uno.config.ts
export default defineConfig({
  safelist: [
    'p-1',
    'p-2',
    'p-3',
    'text-center',
    'bg-red-500'
  ]
})

関数形式

Safelistには、ビルド時に呼び出され、動的にクラス名を返す関数を含めることもできます：

// uno.config.ts
export default defineConfig({
  safelist: [
    // 静的なクラス名
    'p-1',
    'p-2',
    // 動的な関数
    context => ['m-1', 'm-2', 'm-3'],
    (context) => {
      // テーマに基づいてクラス名を生成
      const colors = Object.keys(context.theme.colors || {})
      return colors.map(color => `bg-${color}-500`)
    }
  ]
})

混合使用

同じsafelist設定で文字列と関数を混在させることができます：

// uno.config.ts
export default defineConfig({
  safelist: [
    // 静的なクラス名
    'prose',
    'bg-orange-300',
    // 動的生成
    () => ['flex', 'grid', 'block'],
    // 条件付き動的生成
    (context) => {
      if (process.env.NODE_ENV === 'development') {
        return ['debug-border', 'debug-grid']
      }
      return []
    }
  ]
})

戻り値の型

Safelist関数は以下の型の値を返すことができます：

• Arrayable<string> - 文字列または文字列配列

safelist: [
  // 文字列配列を返す
  () => ['class1', 'class2', 'class3'],

  // 単一の文字列を返す
  () => 'single-class',

  // ネストされた配列を返す（フラット化される）
  () => [['nested1', 'nested2'], 'normal3']
]

実用的な使用例

動的に生成されたクラス名

静的解析では検出されない可能性のある動的に生成されたクラス名がある場合：

safelist: [
  // 動的な色クラス
  () => {
    const dynamicColors = ['primary', 'secondary', 'accent']
    return dynamicColors.flatMap(color => [
      `bg-${color}`,
      `text-${color}`,
      `border-${color}`
    ])
  },

  // 動的なサイズクラス
  () => {
    return Array.from({ length: 12 }, (_, i) => `gap-${i + 1}`)
  }
]

サードパーティのコンポーネントライブラリのサポート

サードパーティのコンポーネントライブラリに必要なクラス名を提供：

safelist: [
  // コンポーネントライブラリ用の予約クラス名
  'prose',
  'prose-sm',
  'prose-lg',

  // コンポーネントのバリアントを動的に生成
  () => {
    const variants = ['primary', 'secondary', 'danger', 'success']
    const sizes = ['sm', 'md', 'lg']

    return variants.flatMap(variant =>
      sizes.map(size => `btn-${variant}-${size}`)
    )
  }
]

他の設定との関係

blocklistとの違い

• safelist: 指定されたクラス名が常に含まれることを保証
• blocklist: 指定されたクラス名が常に除外されることを保証

export default defineConfig({
  safelist: ['always-include'],
  blocklist: ['never-include']
})

生成オプションとの関係

CSSを生成する際に、GenerateOptionsを通じてsafelistを含めるかどうかを制御できます：

const { css } = await uno.generate('', {
  safelist: true // safelistからクラス名を含める
})