0
# @unocss/nuxt
1

2
@unocss/nuxt is a Nuxt module that integrates UnoCSS, the instant on-demand Atomic CSS engine, into Nuxt.js applications. It provides seamless integration with both Vite and Webpack build systems, enabling developers to use UnoCSS's powerful utility-first CSS framework within Nuxt projects with zero runtime overhead and instant compilation.
3

4
## Package Information
5

6
- **Package Name**: @unocss/nuxt
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @unocss/nuxt`
10

11
## Core Imports
12

13
```typescript
14
import UnoCSS from "@unocss/nuxt";
15
```
16

17
For accessing configuration types:
18

19
```typescript
20
import type { UnocssNuxtOptions } from "@unocss/nuxt";
21
```
22

23
For TypeScript projects, both the module and types are available:
24

25
```typescript
26
import UnoCSS, { type UnocssNuxtOptions } from "@unocss/nuxt";
27
```
28

29
## Basic Usage
30

31
Add the module to your `nuxt.config.ts`:
32

33
```typescript
34
export default defineNuxtConfig({
35
  modules: [
36
    '@unocss/nuxt'
37
  ],
38
  unocss: {
39
    // UnoCSS options
40
    preflight: true,
41
    icons: true,
42
  }
43
});
44
```
45

46
## Architecture
47

48
@unocss/nuxt is built around several key components:
49

50
- **Nuxt Module**: Main integration point that configures UnoCSS within the Nuxt ecosystem
51
- **Build Integration**: Automatic plugin registration for both Vite and Webpack build systems
52
- **Configuration System**: Unified options interface extending UnoCSS core configuration
53
- **Preset Management**: Automatic preset resolution and conflict handling
54
- **Runtime Components**: Vue components like `<UnoIcon>` for enhanced functionality
55
- **Development Tools**: Nuxt DevTools integration with UnoCSS panel and hot module replacement support
56

57
## Capabilities
58

59
### Module Configuration
60

61
Core Nuxt module that registers UnoCSS integration with comprehensive configuration options.
62

63
```typescript { .api }
64
/**
65
 * Default export - Nuxt module for UnoCSS integration
66
 */
67
declare const UnoCSS: NuxtModule<UnocssNuxtOptions>;
68
export default UnoCSS;
69

70
/**
71
 * Configuration options interface
72
 */
73
export interface UnocssNuxtOptions extends UserConfig {
74
  /** CSS Generation mode (Vite only, default: 'global') */
75
  mode?: 'global' | 'per-module' | 'vue-scoped' | 'dist-chunk' | 'shadow-dom';
76
  
77
  /** Automatically inject uno.css entry (default: true) */
78
  autoImport?: boolean;
79
  
80
  /** Inject @unocss/reset/tailwind.css entry (default: false) */
81
  preflight?: boolean;
82
  
83
  /** Disable Nuxt's inline styles for UnoCSS compatibility (default: true) */
84
  disableNuxtInlineStyle?: boolean;
85
  
86
  /** Automatically merge UnoCSS configs from Nuxt layers (default: false) */
87
  nuxtLayers?: boolean;
88
  
89
  /** Path to UnoCSS config file (default: ['uno.config', 'unocss.config']) */
90
  configFile?: string | string[];
91
  
92
  /** @deprecated Position control for uno.css injection - temporarily removed due to incompatibility with Nuxt 3.9 */
93
  injectPosition?: 'first' | 'last' | number | { after?: string };
94
  
95
  /** Install UnoCSS components like <UnoIcon> (default: true) */
96
  components?: boolean;
97
  
98
  /** Enable attributify mode and options (default: false) */
99
  attributify?: boolean | AttributifyOptions;
100
  
101
  /** Enable tagify mode and options (default: false) */
102
  tagify?: boolean | TagifyOptions;
103
  
104
  /** Enable icons preset and options (default: false) */
105
  icons?: boolean | IconsOptions;
106
  
107
  /** Enable web fonts preset and options (default: false) */
108
  webFonts?: boolean | WebFontsOptions;
109
  
110
  /** Enable typography preset and options (default: false) */
111
  typography?: boolean | TypographyOptions;
112
  
113
  /** Enable wind3 preset (default: true) */
114
  wind3?: boolean | PresetWind3Options;
115
  
116
  /** Enable wind4 preset (default: false) */
117
  wind4?: boolean | PresetWind4Options;
118
}
119
```
120

121
### Configuration Extensions and Hooks
122

123
Extends Nuxt's configuration schema to include UnoCSS options and provides integration hooks.
124

125
```typescript { .api }
126
/**
127
 * Nuxt configuration schema extensions and hooks
128
 */
129
declare module '@nuxt/schema' {
130
  interface NuxtConfig {
131
    unocss?: UnocssNuxtOptions;
132
  }
133
  
134
  interface NuxtOptions {
135
    unocss?: UnocssNuxtOptions;
136
  }
137
  
138
  interface NuxtHooks {
139
    /**
140
     * Hook called when UnoCSS config loading is completed
141
     */
142
    'unocss:config': (config: UserConfig) => void;
143
  }
144
}
145
```
146

147
### Runtime Components
148

149
Vue components provided by the module for enhanced UnoCSS integration.
150

151
```typescript { .api }
152
/**
153
 * UnoIcon Vue component - basic empty div element
154
 * Available when components option is enabled (default: true)
155
 * Note: This is a placeholder component with no props or functionality
156
 */
157
declare const UnoIcon: DefineComponent;
158
```
159

160
## Types
161

162
### Core Configuration Interface
163

164
```typescript { .api }
165
interface UnocssNuxtOptions extends UserConfig {
166
  mode?: 'global' | 'per-module' | 'vue-scoped' | 'dist-chunk' | 'shadow-dom';
167
  autoImport?: boolean;
168
  preflight?: boolean;
169
  disableNuxtInlineStyle?: boolean;
170
  nuxtLayers?: boolean;
171
  configFile?: string | string[];
172
  injectPosition?: 'first' | 'last' | number | { after?: string };
173
  components?: boolean;
174
  attributify?: boolean | AttributifyOptions;
175
  tagify?: boolean | TagifyOptions;
176
  icons?: boolean | IconsOptions;
177
  webFonts?: boolean | WebFontsOptions;
178
  typography?: boolean | TypographyOptions;
179
  wind3?: boolean | PresetWind3Options;
180
  wind4?: boolean | PresetWind4Options;
181
}
182
```
183

184
### Preset Option Types
185

186
```typescript { .api }
187
/**
188
 * Preset configuration types (imported from respective preset packages)
189
 */
190
type AttributifyOptions = import('@unocss/preset-attributify').AttributifyOptions;
191
type IconsOptions = import('@unocss/preset-icons').IconsOptions;
192
type TagifyOptions = import('@unocss/preset-tagify').TagifyOptions;
193
type TypographyOptions = import('@unocss/preset-typography').TypographyOptions;
194
type WebFontsOptions = import('@unocss/preset-web-fonts').WebFontsOptions;
195
type PresetWind3Options = import('@unocss/preset-wind3').PresetWind3Options;
196
type PresetWind4Options = import('@unocss/preset-wind4').PresetWind4Options;
197
```
198

199
### Base Configuration
200

201
```typescript { .api }
202
/**
203
 * Base UnoCSS configuration (from @unocss/core)
204
 */
205
type UserConfig = import('@unocss/core').UserConfig;
206
```
207

208
## Usage Examples
209

210
### Basic Configuration
211

212
```typescript
213
// nuxt.config.ts
214
export default defineNuxtConfig({
215
  modules: ['@unocss/nuxt'],
216
  unocss: {
217
    // Enable preflight (CSS reset)
218
    preflight: true,
219
    
220
    // Enable UnoCSS icons
221
    icons: true,
222
    
223
    // Enable attributify mode
224
    attributify: true,
225
    
226
    // Use global CSS injection mode
227
    mode: 'global'
228
  }
229
});
230
```
231

232
### Advanced Configuration with Custom Presets
233

234
```typescript
235
// nuxt.config.ts
236
export default defineNuxtConfig({
237
  modules: ['@unocss/nuxt'],
238
  unocss: {
239
    preflight: true,
240
    icons: {
241
      scale: 1.2,
242
      warn: true,
243
      collections: {
244
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
245
      }
246
    },
247
    webFonts: {
248
      provider: 'google',
249
      fonts: {
250
        sans: 'Roboto',
251
        mono: ['Fira Code', 'Fira Mono:400,700']
252
      }
253
    },
254
    shortcuts: {
255
      'btn': 'px-4 py-1 rounded inline-block bg-teal-600 text-white cursor-pointer hover:bg-teal-700 disabled:cursor-default disabled:bg-gray-600 disabled:opacity-50',
256
      'btn-green': 'text-white bg-green-500 hover:bg-green-700',
257
    },
258
    rules: [
259
      [/^m-(\d+)$/, ([, d]) => ({ margin: `${d}px` })],
260
    ]
261
  }
262
});
263
```
264

265
### Using with Nuxt Layers
266

267
```typescript
268
// nuxt.config.ts
269
export default defineNuxtConfig({
270
  modules: ['@unocss/nuxt'],
271
  unocss: {
272
    // Enable automatic config merging from layers
273
    nuxtLayers: true,
274
    
275
    // Specify custom config file paths
276
    configFile: ['uno.config.ts', 'unocss.config.ts'],
277
    
278
    // Base configuration
279
    preflight: true,
280
    wind3: true
281
  }
282
});
283
```
284

285
### TypeScript Configuration
286

287
```typescript
288
// nuxt.config.ts
289
import type { UnocssNuxtOptions } from '@unocss/nuxt';
290

291
const unocssConfig: UnocssNuxtOptions = {
292
  preflight: true,
293
  icons: true,
294
  attributify: true,
295
  wind3: true,
296
  shortcuts: {
297
    'custom-btn': 'bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600'
298
  }
299
};
300

301
export default defineNuxtConfig({
302
  modules: ['@unocss/nuxt'],
303
  unocss: unocssConfig
304
});
305
```
306

307
### Accessing UnoIcon Component
308

309
```vue
310
<template>
311
  <div>
312
    <!-- UnoIcon component automatically available when components: true -->
313
    <!-- Note: UnoIcon is currently a placeholder empty div component -->
314
    <UnoIcon />
315
  </div>
316
</template>
317
```
318

319
### Using the Configuration Hook
320

321
```typescript
322
// plugins/unocss.client.ts
323
export default defineNuxtPlugin(() => {
324
  // Hook into UnoCSS configuration
325
  const nuxtApp = useNuxtApp();
326
  
327
  nuxtApp.hook('unocss:config', (config) => {
328
    console.log('UnoCSS configuration loaded:', config);
329
  });
330
});
331
```
332

333
### Development Tools Integration
334

335
In development mode, the module automatically registers a UnoCSS panel in Nuxt DevTools, accessible at `/__unocss/` for inspecting generated CSS and configuration.