0
# @vueuse/nuxt
1

2
VueUse Nuxt Module provides seamless integration of VueUse composables with automatic import capabilities for Nuxt applications. It enables developers to use Vue Composition API utilities from the VueUse library without manual imports, while intelligently avoiding conflicts with Nuxt's built-in utilities.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
// The module is used in nuxt.config.ts, not imported directly in components
15
export default defineNuxtConfig({
16
  modules: ['@vueuse/nuxt']
17
});
18
```
19

20
For advanced use cases requiring direct access:
21

22
```typescript
23
import nuxtModule from "@vueuse/nuxt";
24
import type { VueUseNuxtOptions } from "@vueuse/nuxt";
25
```
26

27
## Basic Usage
28

29
Add to your Nuxt configuration to enable auto-imports for VueUse composables:
30

31
```typescript
32
// nuxt.config.ts
33
export default defineNuxtConfig({
34
  modules: ['@vueuse/nuxt'],
35
  vueuse: {
36
    // Optional configuration
37
    autoImports: true,     // Enable auto-imports (default: true)
38
    ssrHandlers: false     // Enable SSR handlers (default: false, experimental)
39
  }
40
});
41
```
42

43
Once configured, VueUse composables are automatically available in your components:
44

45
```vue
46
<template>
47
  <div>
48
    <p>Mouse position: {{ x }}, {{ y }}</p>
49
    <p>Window size: {{ width }} x {{ height }}</p>
50
  </div>
51
</template>
52

53
<script setup>
54
// No imports needed - auto-imported by the module
55
const { x, y } = useMouse();
56
const { width, height } = useWindowSize();
57
</script>
58
```
59

60
## Architecture  
61

62
The module consists of several key components:
63

64
- **Module Definition**: Nuxt module that configures VueUse integration
65
- **Auto-Import System**: Automatically imports VueUse composables from multiple packages
66
- **Conflict Avoidance**: Disables VueUse functions that conflict with Nuxt built-ins
67
- **SSR Support**: Optional server-side rendering handlers for VueUse composables
68
- **Build Integration**: Configures Vite and build settings for optimal VueUse usage
69

70
## Capabilities
71

72
### Nuxt Module Configuration  
73

74
The main export that configures VueUse integration in Nuxt applications.
75

76
```typescript { .api }
77
/**
78
 * VueUse Nuxt Module - Auto import for VueUse in Nuxt
79
 */
80
declare const _default: NuxtModule<VueUseNuxtOptions>;
81
export default _default;
82

83
interface VueUseNuxtOptions {
84
  /**
85
   * Enable/disable auto imports for VueUse composables
86
   * @default true
87
   */
88
  autoImports?: boolean;
89
  
90
  /**
91
   * Enable/disable SSR handlers for server-side rendering
92
   * @experimental
93
   * @default false
94
   */
95
  ssrHandlers?: boolean;
96
}
97

98
// Supporting types from @nuxt/kit
99
interface NuxtModule<T = any> {
100
  (options?: T, nuxt?: any): void | Promise<void>;
101
  meta?: ModuleMeta;
102
}
103
```
104

105
### Module Metadata
106

107
Module identification and configuration key.
108

109
```typescript { .api }
110
interface ModuleMeta {
111
  name: 'vueuse';
112
  configKey: 'vueuse';
113
}
114
```
115

116
### Disabled Functions
117

118
VueUse functions that are disabled to avoid conflicts with Nuxt built-ins.
119

120
```typescript { .api }
121
/**
122
 * Functions disabled from auto-import to avoid conflicts with Nuxt
123
 */
124
declare const disabledFunctions: readonly [
125
  'toRefs',
126
  'toRef', 
127
  'toValue',
128
  'useFetch',
129
  'useCookie',
130
  'useHead',
131
  'useStorage',
132
  'useImage'
133
];
134
```
135

136
### Supported VueUse Packages
137

138
VueUse packages that are automatically imported when available.
139

140
```typescript { .api }
141
/**
142
 * VueUse packages supported for auto-import
143
 */
144
declare const packages: readonly [
145
  'core',
146
  'shared',
147
  'components', 
148
  'motion',
149
  'firebase',
150
  'rxjs',
151
  'sound',
152
  'math',
153
  'router'
154
];
155
```
156

157
### Auto-Import Configuration
158

159
The module automatically imports VueUse composables from the following packages when they are available:
160

161
- `@vueuse/core` - Core composables (always available)
162
- `@vueuse/components` - Vue component utilities  
163
- `@vueuse/motion` - Animation and motion utilities
164
- `@vueuse/firebase` - Firebase integration
165
- `@vueuse/rxjs` - RxJS integration
166
- `@vueuse/sound` - Audio utilities
167
- `@vueuse/math` - Mathematical utilities  
168
- `@vueuse/router` - Vue Router utilities
169

170
Only functions with names 4+ characters that don't conflict with disabled functions are auto-imported.
171

172
### SSR Plugin Support
173

174
When `ssrHandlers: true` is enabled, the module provides server-side rendering support:
175

176
```typescript { .api }
177
/**
178
 * SSR handlers for VueUse composables in server context
179
 */
180
interface SSRHandlers {
181
  /**
182
   * Provides cookie-based storage implementation for SSR
183
   * Uses Nuxt's useCookie for persistent storage
184
   */
185
  getDefaultStorage(): {
186
    getItem(key: string): any;
187
    setItem(key: string, value: any): void;
188
    removeItem(key: string): void;
189
  };
190
  
191
  /**
192
   * Updates HTML attributes in SSR context
193
   * Supports 'html' and 'body' selectors via useHead
194
   */
195
  updateHTMLAttrs(selector: 'html' | 'body', attr: string, value: any): void;
196
}
197
```
198

199
### Build Configuration
200

201
The module automatically configures:
202

203
- **Vite Optimization**: Excludes VueUse packages from dependency optimization
204
- **Transpilation**: Adds VueUse packages to Nuxt's transpile targets  
205
- **DevTools Integration**: Adds VueUse documentation tab to Nuxt DevTools
206

207
### Nuxt Schema Extensions
208

209
Extends Nuxt's configuration types to include VueUse options.
210

211
```typescript { .api }
212
declare module '@nuxt/schema' {
213
  interface NuxtConfig {
214
    vueuse?: VueUseNuxtOptions;
215
  }
216
  
217
  interface NuxtOptions {
218
    vueuse?: VueUseNuxtOptions;
219
  }
220
}
221
```
222

223
## Error Handling
224

225
The module handles several error scenarios:
226

227
- **Missing Packages**: Gracefully skips auto-imports for VueUse packages that aren't installed
228
- **SSR Conflicts**: When SSR handlers encounter unsupported meta selectors, throws descriptive errors
229
- **Build Issues**: Automatically configures build settings to prevent common VueUse + Nuxt conflicts
230

231
## CommonJS Compatibility
232

233
A CommonJS proxy is provided for legacy module systems:
234

235
```typescript { .api }
236
/**
237
 * CommonJS proxy to bypass jiti transforms from Nuxt 2
238
 */
239
declare const commonjsProxy: {
240
  default: (...args: any[]) => Promise<any>;
241
  meta: {
242
    name: string;
243
    version: string;
244
    [key: string]: any;
245
  };
246
};
247
```