0Pricing
Tailwind CSS Academy · 课时

动态类名安全列表

使用 tailwind.config.js 中的 safelist 选项，确保 JIT 无法静态检测到的动态构造类名始终被包含。

动态类名安全列表 是 CoddyKit 上的免费 Tailwind CSS Academy 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Tailwind CSS Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Tailwind CSS Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

The Safe-Listing Problem

JIT's static scan is a strength for most cases, but it creates a challenge when class names are determined at runtime — from a database, an API response, or a user's color preferences. These dynamically determined class names never appear as complete strings in your source files, so JIT does not generate them.

The safelist in tailwind.config.js is the official solution: you explicitly list classes (or patterns) that JIT must always generate, regardless of whether they appear in your template files.

Basic Safelist Configuration

Add a safelist array to your tailwind.config.js. List any complete class names that JIT cannot detect statically. JIT will always generate CSS for every class in this array, even if it does not find them in your content files.

This is the simplest form of safe-listing — individual class names. It works well for a small number of known dynamic classes.

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,ts}'],
  safelist: [
    'bg-red-500',
    'bg-green-500',
    'bg-blue-500',
    'bg-yellow-500',
    'text-white',
    'text-gray-900',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Pattern-Based Safelisting

For dynamic values across an entire color scale, listing every individual class is tedious. Instead, use a pattern object in the safelist that specifies a regex pattern. JIT will generate all classes matching the pattern.

For example, to generate all background colors for alert levels (red, green, yellow, blue) across shades 100 and 700, you can use a pattern that matches exactly those combinations.

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js}'],
  safelist: [
    // Generate all bg-* text-* combinations for status colors
    {
      pattern: /bg-(red|green|blue|yellow|purple)-(100|500|700)/,
    },
    {
      pattern: /text-(red|green|blue|yellow|purple)-(700|800|900)/,
    },
    {
      pattern: /border-(red|green|blue|yellow|purple)-(300|500)/,
    },
  ],
  theme: {
    extend: {},
  },
}

Generating Variants With Patterns

Pattern-based safelisting also supports generating variants alongside the base class. Add a variants array to the pattern object to include hover, focus, dark, and responsive variants.

This is essential when the dynamically determined class is used inside interactive elements. For example, a status badge that changes color based on a database field needs its hover state generated too if the badge is a clickable button.

// tailwind.config.js
module.exports = {
  safelist: [
    {
      pattern: /bg-(red|green|blue|yellow)-(100|200|500|600)/,
      variants: ['hover', 'focus', 'dark', 'dark:hover'],
    },
    {
      pattern: /text-(red|green|blue|yellow)-(600|700|800)/,
      variants: ['hover', 'dark'],
    },
  ],
}

When to Use Safelisting

The safelist should be a last resort, not a first instinct. Before safe-listing, consider these alternatives:

  • Map values to full class strings in a JavaScript object — the cleanest solution
  • Inline styles for truly arbitrary runtime values like user-chosen hex colors
  • CSS variables with a fixed Tailwind class that references the variable

Overusing the safelist defeats the purpose of JIT and can re-introduce the problem of large CSS files.

// Preferred: map values to complete class strings
const statusClasses = {
  success: 'bg-green-100 text-green-800 border-green-300',
  error:   'bg-red-100 text-red-800 border-red-300',
  warning: 'bg-yellow-100 text-yellow-800 border-yellow-300',
  info:    'bg-blue-100 text-blue-800 border-blue-300',
};

// Usage in template:
// class={statusClasses[status]}
// JIT detects all four strings statically — no safelist needed!

Inline Styles for Truly Dynamic Values

When a value is truly arbitrary at runtime — like a user's custom brand color stored in a database — inline styles are the right tool. Tailwind utilities map to fixed values on the design scale, while inline styles can accept any computed value.

Combine Tailwind for layout and structure with inline styles for the one truly dynamic value. This keeps 99% of your styling in Tailwind and reserves inline styles for the specific dynamic case.

<!-- User's custom brand color from database -->
<div
  class="px-6 py-4 rounded-xl font-semibold text-white"
  style="background-color: {{ user.brandColor }}">
  Custom Brand Header
</div>

<!-- The layout, padding, rounding, and text color all use Tailwind utilities -->
<!-- Only the dynamic database value uses inline style -->
<!-- This keeps the JIT stylesheet small and Tailwind responsible for design scale -->

<!-- CSS variable approach (also good):
<style> :root { --brand: {{ user.brandColor }}; } </style>
<div class="bg-[var(--brand)] px-6 py-4 rounded-xl text-white">...</div>
-->

CSS Variables as Dynamic Values

A powerful technique is to set a CSS variable to the dynamic value and reference it with Tailwind's arbitrary value syntax: bg-[var(--brand-color)]. The class string bg-[var(--brand-color)] is a complete static string that JIT can detect and generate.

The CSS variable itself is then updated dynamically via JavaScript or inline styles on a parent element, while the class stays fixed in your template.

<!-- Static class referencing a CSS variable -->
<div
  id="card"
  class="bg-[var(--card-bg)] text-[var(--card-text)] px-6 py-4 rounded-xl">
  Dynamically colored card
</div>

<script>
  // Update the CSS variable dynamically
  const card = document.getElementById('card');
  card.style.setProperty('--card-bg', '#1a1a2e');
  card.style.setProperty('--card-text', '#e0e0e0');

  // The class 'bg-[var(--card-bg)]' is a static string
  // JIT generates it because it appears literally in the HTML
</script>

Safelist in a Monorepo or Component Library

When building a component library that other projects will consume, classes in your library's components must be included in the consuming project's JIT scan. Include the library's source in the content array of the consumer's config, or use a preset that ships a safelist.

If the library ships compiled JavaScript (not source HTML), add the package path to the consumer's content glob, pointing to the compiled JS files that still contain the class strings as literal strings.

// Consumer project's tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{html,js,ts,tsx}',
    // Include the UI library's compiled files so JIT finds its classes
    './node_modules/@my-company/ui/**/*.{js,ts}',
  ],
  safelist: [
    // Or explicitly list classes the library uses dynamically
    {
      pattern: /bg-(blue|red|green|gray)-(50|100|500|600|700)/,
    },
  ],
}

Verifying the Safelist Works

After adding classes to the safelist, verify they are being generated by inspecting the compiled CSS output. Run npx tailwindcss -i input.css -o output.css and search the output file for one of the safelisted classes.

If the class is missing, double-check the regex pattern in the safelist (regex errors are silent). You can also temporarily add the class as a string to the safelist to confirm the configuration is being read at all.

# Build and verify
npx tailwindcss -i input.css -o output.css

# Check if safelisted class is in output:
grep 'bg-red-500' output.css
# Should print: .bg-red-500 { background-color: #ef4444; }

# If missing, test with direct string:
# safelist: ['bg-red-500'] -- if this works, your regex is wrong

# Regex debugging:
const pattern = /bg-(red|green)-(100|500)/;
console.log(pattern.test('bg-red-500')); // true
console.log(pattern.test('bg-red-600')); // false -- 600 not in pattern

Blocklist to Exclude Classes

The opposite of a safelist is a blocklist — classes you want to prevent from being generated even if JIT detects them in your templates. This is rarely needed but useful when you are overriding Tailwind classes with custom CSS and want to avoid specificity conflicts from the generated utilities.

Add a blocklist array to tailwind.config.js with class names to exclude. JIT will skip these even if found in content files.

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js}'],
  blocklist: [
    // Prevent these classes from being generated
    // (e.g., you have custom .container styles that conflict)
    'container',
    // Prevent a whole pattern:
    // blocklist does NOT support regex -- individual names only
  ],
  theme: {
    extend: {},
  },
}

Safelisting From External Data Sources

In headless CMS projects, blog platforms, or user-themeable apps, class names may come from a database or CMS content field. The safelist should cover the set of all possible values the CMS allows users to choose from.

Document the allowed class set, restrict CMS inputs to that set, and mirror the restriction in the safelist pattern. This ensures no class is used in content that is not generated in the stylesheet — a common bug in CMS-driven Tailwind projects.

// Allowed alert colors in your CMS:
// success, error, warning, info
// Tailwind classes for each stored in CMS: 'bg-green-100', 'bg-red-100', etc.

// tailwind.config.js safelist:
module.exports = {
  safelist: [
    // Exact list matching what CMS allows
    'bg-green-100', 'text-green-800', 'border-green-300',
    'bg-red-100', 'text-red-800', 'border-red-300',
    'bg-yellow-100', 'text-yellow-800', 'border-yellow-300',
    'bg-blue-100', 'text-blue-800', 'border-blue-300',
  ],
}

Quick Check

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

Lesson Recap

In this lesson you learned: the safelist in tailwind.config.js forces JIT to generate classes regardless of whether they appear in scanned content files; pattern objects with regex values generate entire sets of related classes efficiently; and the best alternatives to safelisting are mapping dynamic values to complete class strings in JS objects, using inline styles for truly arbitrary runtime values, or leveraging CSS variables referenced with Tailwind's arbitrary value syntax. Next up we analyze and reduce bundle size.

常见问题解答

「动态类名安全列表」课时是免费的吗？

是的 — 「动态类名安全列表」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Tailwind CSS Academy 课程的其余内容，请升级到 CoddyKit PRO。 Tailwind CSS Academy 课程共包含 4 节课。

「动态类名安全列表」这节课中我会学到什么？

使用 tailwind.config.js 中的 safelist 选项，确保 JIT 无法静态检测到的动态构造类名始终被包含。 你通过在浏览器中直接运行的动手代码来练习 Tailwind CSS Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Tailwind CSS Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Tailwind CSS Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。

「动态类名安全列表」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Tailwind CSS Academy 课中编写并运行代码吗？

能。每节 Tailwind CSS Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. JIT 引擎的工作原理
  2. 动态类名安全列表
  3. 分析并缩减捆绑包大小
  4. 任意值及其代价
← 返回 Tailwind CSS Academy