0
# Auto-Imports System
1

2
Auto-import registration and management for both client-side and server-side code. Enables automatic importing of functions, composables, and utilities without explicit import statements.
3

4
## Capabilities
5

6
### Client-Side Auto-Imports
7

8
Register auto-imports for client-side and universal code.
9

10
```typescript { .api }
11
/**
12
 * Add auto-imports to the imports system
13
 * @param imports - Import or array of imports to register
14
 */
15
function addImports(imports: Import | Import[]): void;
16

17
/**
18
 * Add directories to be scanned for auto-imports
19
 * @param dirs - Directory path(s) to scan
20
 * @param opts - Directory scanning options
21
 */
22
function addImportsDir(
23
  dirs: string | string[],
24
  opts?: { prepend?: boolean }
25
): void;
26

27
/**
28
 * Add import sources/presets for auto-imports
29
 * @param presets - Import preset(s) to register
30
 */
31
function addImportsSources(
32
  presets: ImportPresetWithDeprecation | ImportPresetWithDeprecation[]
33
): void;
34

35
interface Import {
36
  /** Function/variable name to import */
37
  name: string;
38
  /** Alternative name to use locally */
39
  as?: string;
40
  /** Module to import from */
41
  from: string;
42
  /** Named import (default: true) */
43
  type?: boolean;
44
  /** Type import only */
45
  typeOnly?: boolean;
46
  /** Import priority */
47
  priority?: number;
48
  /** Disabled flag */
49
  disabled?: boolean;
50
  /** Import metadata */
51
  meta?: ImportMeta;
52
}
53

54
interface ImportMeta {
55
  /** Function description */
56
  description?: string;
57
  /** Function documentation URL */
58
  docsUrl?: string;
59
  /** Import category */
60
  category?: string;
61
  [key: string]: any;
62
}
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { addImports, addImportsDir, addImportsSources } from "@nuxt/kit";
69

70
// Add individual imports
71
addImports([
72
  { name: "useMyComposable", from: "~/composables/useMyComposable" },
73
  { name: "myUtility", from: "~/utils/myUtility" },
74
  { name: "default", as: "MyClass", from: "~/classes/MyClass" }
75
  {
76
    name: "computed", 
77
    from: "vue",
78
    type: true // TypeScript type import
79
  }
80
]);
81

82
// Add directory for auto-scanning
83
addImportsDir([
84
  "~/composables",
85
  "~/utils"
86
]);
87

88
// Add with prepend (higher priority)
89
addImportsDir("~/priority-utils", { prepend: true });
90

91
// Add import presets
92
addImportsSources([
93
  {
94
    from: "lodash-es",
95
    imports: ["debounce", "throttle", "cloneDeep"]
96
  },
97
  {
98
    from: "@vueuse/core",
99
    imports: ["useStorage", "useFetch", "useToggle"]
100
  }
101
]);
102
```
103

104
### Server-Side Auto-Imports
105

106
Register auto-imports specifically for server-side and Nitro code.
107

108
```typescript { .api }
109
/**
110
 * Add server-side auto-imports for Nitro
111
 * @param imports - Import or array of imports to register
112
 */
113
function addServerImports(imports: Import | Import[]): void;
114

115
/**
116
 * Add directories to be scanned for server auto-imports
117
 * @param dirs - Directory path(s) to scan
118
 * @param opts - Directory scanning options
119
 */
120
function addServerImportsDir(
121
  dirs: string | string[],
122
  opts?: { prepend?: boolean }
123
): void;
124

125
/**
126
 * Add directories to be scanned by Nitro like ~/server
127
 * @param dirs - Directory path(s) to scan
128
 * @param opts - Directory scanning options
129
 */
130
function addServerScanDir(
131
  dirs: string | string[],
132
  opts?: { prepend?: boolean }
133
): void;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
import { 
140
  addServerImports, 
141
  addServerImportsDir, 
142
  addServerScanDir 
143
} from "@nuxt/kit";
144

145
// Add server-specific imports
146
addServerImports([
147
  { name: "useServerDatabase", from: "~/server/utils/database" },
148
  { name: "validateRequest", from: "~/server/utils/validation" }
149
]);
150

151
// Add server utils directory
152
addServerImportsDir([
153
  "~/server/utils",
154
  "~/server/composables"
155
]);
156

157
// Add server scan directories (for API routes, middleware, etc.)
158
addServerScanDir([
159
  "~/server/custom-api",
160
  "~/server/custom-middleware"
161
]);
162
```
163

164
### Import Presets and Sources
165

166
Configure bulk imports from packages and libraries.
167

168
```typescript { .api }
169
interface ImportPresetWithDeprecation {
170
  /** Package name to import from */
171
  from: string;
172
  /** List of imports from the package */
173
  imports: (string | ImportPresetImport)[];
174
  /** Import all as namespace */
175
  as?: string;
176
  /** Deprecation message */
177
  deprecatedFrom?: string;
178
  /** Import priority */
179
  priority?: number;
180
}
181

182
interface ImportPresetImport {
183
  /** Import name */
184
  name: string;
185
  /** Local alias */
186
  as?: string;
187
  /** Type import only */
188
  type?: boolean;
189
}
190
```
191

192
**Usage Examples:**
193

194
```typescript
195
import { addImportsSources } from "@nuxt/kit";
196

197
// Vue ecosystem imports
198
addImportsSources([
199
  {
200
    from: "vue",
201
    imports: [
202
      "ref",
203
      "reactive",
204
      "computed",
205
      "watch",
206
      "onMounted",
207
      "onUnmounted",
208
      { name: "defineComponent", type: true }
209
    ]
210
  },
211
  {
212
    from: "vue-router",
213
    imports: ["useRoute", "useRouter", "RouteLocationRaw"]
214
  }
215
]);
216

217
// Utility library imports
218
addImportsSources([
219
  {
220
    from: "lodash-es",
221
    imports: [
222
      "debounce",
223
      "throttle", 
224
      "merge",
225
      "cloneDeep",
226
      "isEqual"
227
    ]
228
  },
229
  {
230
    from: "date-fns",
231
    imports: [
232
      "format",
233
      "parseISO",
234
      "addDays",
235
      "differenceInDays"
236
    ]
237
  }
238
]);
239

240
// Namespace imports
241
addImportsSources([
242
  {
243
    from: "three",
244
    as: "THREE"
245
  }
246
]);
247
```
248

249
### Auto-Import Configuration
250

251
Control auto-import behavior and discovery patterns.
252

253
**Module-Level Configuration:**
254

255
```typescript
256
export default defineNuxtModule({
257
  setup(options, nuxt) {
258
    // Configure auto-imports for your module
259
    addImports([
260
      {
261
        name: "useMyModuleState",
262
        from: resolve(runtimeDir, "composables"),
263
        meta: {
264
          description: "Access module state",
265
          category: "My Module"
266
        }
267
      }
268
    ]);
269

270
    // Add module utilities directory
271
    addImportsDir(resolve(runtimeDir, "utils"));
272
  }
273
});
274
```
275

276
**Directory Structure for Auto-Discovery:**
277

278
```
279
composables/
280
├── useAuth.ts              → auto-imported as useAuth
281
├── useStorage.ts           → auto-imported as useStorage
282
├── user/
283
│   ├── useProfile.ts       → auto-imported as useProfile
284
│   └── useSettings.ts      → auto-imported as useSettings
285
utils/
286
├── formatters.ts           → exports auto-imported
287
├── validators.ts           → exports auto-imported
288
└── api.ts                  → exports auto-imported
289
```
290

291
**File Export Patterns:**
292

293
```typescript
294
// composables/useCounter.ts - default export
295
export default function useCounter() {
296
  const count = ref(0);
297
  return { count };
298
}
299

300
// utils/formatters.ts - named exports
301
export function formatCurrency(amount: number) {
302
  return new Intl.NumberFormat("en-US", {
303
    style: "currency",
304
    currency: "USD"
305
  }).format(amount);
306
}
307

308
export function formatDate(date: Date) {
309
  return date.toLocaleDateString();
310
}
311
```
312

313
## Types
314

315
```typescript { .api }
316
interface ImportSources {
317
  /** Global imports configuration */
318
  global?: boolean;
319
  /** Preset imports from packages */
320
  presets?: ImportPresetWithDeprecation[];
321
  /** Custom import directories */
322
  dirs?: string[];
323
  /** Transform function for imports */
324
  transform?: (imports: Import[]) => Import[];
325
}
326
```