1# Tailwind CSS Dynamic Class Generation
2 
3## Rule
4 
5Never construct Tailwind CSS class names dynamically using string concatenation or template literals. Tailwind's build process cannot detect dynamically generated class names, causing styles to be missing in production.
6 
7## Why This Matters
8 
9- Tailwind uses static analysis at build time to determine which CSS classes to include
10- Dynamically constructed class names (e.g., `bg-${color}-500`) are invisible to Tailwind's scanner
11- Classes work in development with JIT but fail silently in production builds
12- This is a common source of "it works locally but not in production" bugs
13 
14## Bad Code
15 
16```vue
17<script setup>
18const props = defineProps({
19  color: String, // 'red', 'blue', 'green'
20  size: String   // 'sm', 'md', 'lg'
21})
22</script>
23 
24<template>
25  <!-- WRONG: Tailwind cannot detect these classes -->
26  <div :class="`bg-${color}-500 text-${size}`">
27    Content
28  </div>
29 
30  <!-- WRONG: String concatenation -->
31  <div :class="'p-' + padding">
32    Content
33  </div>
34 
35  <!-- WRONG: Template literal in array -->
36  <div :class="[`gap-x-${spacing}`]">
37    Content
38  </div>
39</template>
40```
41 
42## Good Code
43 
44```vue
45<script setup>
46const props = defineProps({
47  color: String,
48  size: String
49})
50 
51// Use a mapping object with complete class names
52const colorClasses = {
53  red: 'bg-red-500',
54  blue: 'bg-blue-500',
55  green: 'bg-green-500'
56}
57 
58const sizeClasses = {
59  sm: 'text-sm p-2',
60  md: 'text-base p-4',
61  lg: 'text-lg p-6'
62}
63</script>
64 
65<template>
66  <!-- CORRECT: Full class names that Tailwind can detect -->
67  <div :class="[colorClasses[color], sizeClasses[size]]">
68    Content
69  </div>
70</template>
71```
72 
73## Using Conditional Objects
74 
75```vue
76<script setup>
77const props = defineProps({
78  variant: String // 'primary', 'secondary', 'danger'
79})
80</script>
81 
82<template>
83  <!-- CORRECT: All class names are complete strings -->
84  <button :class="{
85    'bg-blue-500 hover:bg-blue-600': variant === 'primary',
86    'bg-gray-500 hover:bg-gray-600': variant === 'secondary',
87    'bg-red-500 hover:bg-red-600': variant === 'danger'
88  }">
89    Click me
90  </button>
91</template>
92```
93 
94## Safelist for Truly Dynamic Classes
95 
96If you must use dynamic classes, add them to Tailwind's safelist:
97 
98```javascript
99// tailwind.config.js
100module.exports = {
101  safelist: [
102    'bg-red-500',
103    'bg-blue-500',
104    'bg-green-500',
105    // Or use patterns (use sparingly - increases bundle size)
106    {
107      pattern: /bg-(red|blue|green)-(100|500|900)/
108    }
109  ]
110}
111```
112 
113## Alternative: CSS Custom Properties
114 
115For truly dynamic values, use CSS custom properties:
116 
117```vue
118<script setup>
119const props = defineProps({
120  customColor: String // Any hex color
121})
122</script>
123 
124<template>
125  <!-- Use CSS variable for truly dynamic values -->
126  <div
127    class="dynamic-bg"
128    :style="{ '--dynamic-color': customColor }"
129  >
130    Content
131  </div>
132</template>
133 
134<style>
135.dynamic-bg {
136  background-color: var(--dynamic-color);
137}
138</style>
139```
140 
141## References
142 
143- [Tailwind CSS Dynamic Class Names](https://tailwindcss.com/docs/content-configuration#dynamic-class-names)
144- [Tailwind Safelist](https://tailwindcss.com/docs/content-configuration#safelisting-classes)
145