0
# Configuration Utilities
1

2
Utilities for creating and managing Tailwind CSS configurations with Nuxt-specific enhancements and context management.
3

4
## Capabilities
5

6
### Define Configuration
7

8
Creates a Tailwind CSS configuration with Nuxt context awareness and intelligent fallbacks.
9

10
```typescript { .api }
11
/**
12
 * Creates a Tailwind CSS configuration with Nuxt context awareness
13
 * @param config - Partial Tailwind configuration object
14
 * @returns The configuration object or fallback config
15
 */
16
function defineConfig(config: Partial<TWConfig>): Partial<TWConfig>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
// tailwind.config.ts
23
import { defineConfig } from '@nuxtjs/tailwindcss/config';
24

25
export default defineConfig({
26
  content: [
27
    './components/**/*.{js,vue,ts}',
28
    './layouts/**/*.vue',
29
    './pages/**/*.vue',
30
    './plugins/**/*.{js,ts}',
31
    './nuxt.config.{js,ts}',
32
    './app.vue'
33
  ],
34
  theme: {
35
    extend: {
36
      colors: {
37
        primary: {
38
          50: '#eff6ff',
39
          500: '#3b82f6',
40
          900: '#1e3a8a',
41
        }
42
      },
43
      fontFamily: {
44
        sans: ['Inter', 'sans-serif'],
45
      },
46
      spacing: {
47
        '18': '4.5rem',
48
        '88': '22rem',
49
      }
50
    }
51
  },
52
  plugins: [
53
    require('@tailwindcss/forms'),
54
    require('@tailwindcss/typography'),
55
  ]
56
});
57
```
58

59
```javascript
60
// tailwind.config.js (CommonJS)
61
const { defineConfig } = require('@nuxtjs/tailwindcss/config');
62

63
module.exports = defineConfig({
64
  theme: {
65
    extend: {
66
      colors: {
67
        brand: '#ff6b6b'
68
      }
69
    }
70
  }
71
});
72
```
73

74
### Configuration Context
75

76
Internal context management for Tailwind configuration state.
77

78
```typescript { .api }
79
/**
80
 * Context instance for managing Tailwind configuration state
81
 */
82
const ctx: UnctxInstance<boolean>;
83
```
84

85
The context automatically handles:
86
- Nuxt environment detection
87
- Configuration fallbacks when outside Nuxt context
88
- Integration with module's internal configuration loading
89

90
**Context Initialization:**
91

92
```typescript
93
// @nuxtjs/tailwindcss/config-ctx - Sets context for configuration loading
94
import '@nuxtjs/tailwindcss/config-ctx';
95
```
96

97
This import is used internally by the module to initialize the configuration context. It should typically not be imported directly by end users, but may be needed in certain advanced configuration scenarios.
98

99
### Configuration Merger
100

101
Merges multiple Tailwind CSS configuration objects with special handling for content arrays and objects.
102

103
```typescript { .api }
104
/**
105
 * Merges Tailwind CSS configuration objects with special content merging logic
106
 * @param base - Base configuration object
107
 * @param defaults - Additional configuration objects to merge
108
 * @returns Merged configuration object
109
 */
110
function configMerger(
111
  base: Partial<TWConfig> | null | undefined,
112
  ...defaults: Array<Partial<TWConfig> | null | undefined>
113
): Partial<TWConfig>;
114
```
115

116
**Special Merging Behavior:**
117

118
The merger has intelligent logic for the `content` property:
119

120
1. **Array + Object**: Merges array into object's `files` property
121
2. **Object + Array**: Merges array into object's `files` property  
122
3. **Function Handling**: Preserves and calls content functions with appropriate arguments
123

124
**Usage Examples:**
125

126
```typescript
127
import configMerger from '@nuxtjs/tailwindcss/merger';
128

129
// Merge configurations
130
const baseConfig = {
131
  content: ['./pages/**/*.vue'],
132
  theme: {
133
    colors: { primary: 'blue' }
134
  }
135
};
136

137
const overrides = {
138
  content: {
139
    files: ['./components/**/*.vue'],
140
    extract: {
141
      vue: (content) => content.match(/class="([^"]*)"/) || []
142
    }
143
  },
144
  theme: {
145
    colors: { secondary: 'red' }
146
  }
147
};
148

149
const merged = configMerger(baseConfig, overrides);
150
// Result: {
151
//   content: {
152
//     files: ['./pages/**/*.vue', './components/**/*.vue'],
153
//     extract: { vue: (content) => ... }
154
//   },
155
//   theme: {
156
//     colors: { primary: 'blue', secondary: 'red' }
157
//   }
158
// }
159
```
160

161
```typescript
162
// Function-based content merging
163
const config1 = {
164
  content: (files) => [...files, './custom/**/*.vue']
165
};
166

167
const config2 = {
168
  content: ['./base/**/*.vue']
169
};
170

171
const merged = configMerger(config1, config2);
172
// The function receives the array and can transform it
173
```
174

175
### Type Definitions
176

177
Core types used by the configuration utilities.
178

179
```typescript { .api }
180
type TWConfig = import('tailwindcss').Config;
181

182
type Input = Partial<TWConfig> | Record<PropertyKey, any> | null | undefined;
183

184
interface UnctxInstance<T> {
185
  tryUse(): T | undefined;
186
  use(): T;
187
  set(instance: T, replace?: boolean): void;
188
}
189
```
190

191
## Integration with Nuxt
192

193
The configuration utilities integrate seamlessly with Nuxt's module system:
194

195
1. **Context Detection**: `defineConfig` automatically detects Nuxt environment
196
2. **Fallback Behavior**: Provides appropriate fallbacks when used outside Nuxt
197
3. **Module Integration**: Works with the main module's configuration loading system
198
4. **Layer Support**: Supports Nuxt layers and configuration inheritance
199

200
## Error Handling
201

202
The utilities handle various edge cases:
203

204
- **Missing Tailwind**: Graceful fallback when Tailwind CSS is not installed
205
- **Invalid Configurations**: Validates and sanitizes configuration objects
206
- **Context Errors**: Handles cases where Nuxt context is unavailable
207
- **Merge Conflicts**: Resolves configuration conflicts intelligently