0
# Path Resolution & File Utilities
1

2
Path resolution, alias handling, and file discovery with Nuxt-aware logic. Provides utilities for resolving paths, finding files, and handling aliases within the Nuxt ecosystem.
3

4
## Capabilities
5

6
### Path Resolution
7

8
Resolve paths with Nuxt-aware alias support and extension handling.
9

10
```typescript { .api }
11
/**
12
 * Resolve full path respecting Nuxt aliases and extensions
13
 * @param path - Path to resolve
14
 * @param opts - Resolution options
15
 * @returns Promise resolving to full resolved path
16
 */
17
function resolvePath(path: string, opts?: ResolvePathOptions): Promise<string>;
18

19
/**
20
 * Resolve path aliases
21
 * @param path - Path with potential aliases
22
 * @param alias - Alias mapping object
23
 * @returns Resolved path string
24
 */
25
function resolveAlias(
26
  path: string,
27
  alias?: Record<string, string>
28
): string;
29

30
interface ResolvePathOptions {
31
  /** Current working directory */
32
  cwd?: string;
33
  /** File extensions to try */
34
  extensions?: string[];
35
  /** Alias mappings */
36
  alias?: Record<string, string>;
37
  /** Resolve as URL */
38
  url?: boolean;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { resolvePath, resolveAlias } from "@nuxt/kit";
46

47
// Resolve with Nuxt aliases
48
const componentPath = await resolvePath("~/components/MyComponent.vue");
49
// Returns: /path/to/project/components/MyComponent.vue
50

51
const utilPath = await resolvePath("@/utils/helpers");
52
// Returns: /path/to/project/utils/helpers.ts (with extension resolution)
53

54
// Custom alias resolution
55
const aliasedPath = resolveAlias("@custom/module", {
56
  "@custom": "/path/to/custom"
57
});
58
// Returns: /path/to/custom/module
59

60
// Advanced path resolution
61
const resolvedPath = await resolvePath("~/composables/useAuth", {
62
  extensions: [".ts", ".js", ".mjs"],
63
  cwd: "/custom/working/dir"
64
});
65
```
66

67
### File Discovery
68

69
Find and resolve files with pattern matching and ignore pattern support.
70

71
```typescript { .api }
72
/**
73
 * Find first existing file in paths
74
 * @param paths - Path or array of paths to check
75
 * @param opts - Path resolution options
76
 * @param pathType - Type of path to resolve
77
 * @returns Promise resolving to first found path or null
78
 */
79
function findPath(
80
  paths: string | string[],
81
  opts?: ResolvePathOptions,
82
  pathType?: PathType
83
): Promise<string | null>;
84

85
/**
86
 * Resolve files in directory matching pattern, respecting .nuxtignore
87
 * @param path - Directory path to scan
88
 * @param pattern - Glob pattern(s) to match
89
 * @param opts - File resolution options
90
 * @returns Promise resolving to array of matching file paths
91
 */
92
function resolveFiles(
93
  path: string,
94
  pattern: string | string[],
95
  opts?: any
96
): Promise<string[]>;
97

98
type PathType = "file" | "dir";
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import { findPath, resolveFiles } from "@nuxt/kit";
105

106
// Find first existing config file
107
const configPath = await findPath([
108
  "nuxt.config.ts",
109
  "nuxt.config.js",
110
  "nuxt.config.mjs"
111
]);
112

113
// Find component file
114
const component = await findPath("~/components/MyComponent", {
115
  extensions: [".vue", ".ts", ".js"]
116
});
117

118
// Resolve all Vue components in directory
119
const components = await resolveFiles(
120
  "~/components",
121
  "**/*.vue"
122
);
123

124
// Resolve with multiple patterns
125
const sourceFiles = await resolveFiles(
126
  "~/src",
127
  ["**/*.ts", "**/*.js", "!**/*.test.*"]
128
);
129

130
// Resolve TypeScript files only
131
const tsFiles = await resolveFiles(
132
  "~/utils",
133
  "**/*.ts",
134
  { ignore: ["**/*.d.ts"] }
135
);
136
```
137

138
### Resolver Creation
139

140
Create reusable path resolvers for consistent path resolution within modules.
141

142
```typescript { .api }
143
/**
144
 * Create a relative resolver for paths
145
 * @param base - Base path or URL for relative resolution
146
 * @returns Resolver object with resolve methods
147
 */
148
function createResolver(base: string | URL): Resolver;
149

150
interface Resolver {
151
  /** Resolve path relative to base */
152
  resolve(...paths: string[]): string;
153
  /** Resolve path relative to base and ensure it exists */
154
  resolvePath(path: string, opts?: ResolvePathOptions): Promise<string>;
155
}
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
import { createResolver } from "@nuxt/kit";
162
import { fileURLToPath } from "node:url";
163

164
// Create resolver from import.meta.url
165
const resolver = createResolver(import.meta.url);
166

167
// Resolve relative to current file
168
const templatePath = resolver.resolve("./templates/component.vue");
169
const configPath = resolver.resolve("../config/default.json");
170

171
// Module resolver pattern
172
export default defineNuxtModule({
173
  setup(options, nuxt) {
174
    const resolver = createResolver(import.meta.url);
175
    
176
    // Resolve runtime directory
177
    const runtimeDir = resolver.resolve("./runtime");
178
    
179
    // Add plugin from resolved path
180
    addPlugin({
181
      src: resolver.resolve("./runtime/plugin.mjs"),
182
      mode: "all"
183
    });
184
    
185
    // Add template with resolved source
186
    addTemplate({
187
      src: resolver.resolve("./templates/config.mjs"),
188
      filename: "my-module-config.mjs"
189
    });
190
  }
191
});
192

193
// Resolver with path validation
194
const resolver = createResolver(import.meta.url);
195

196
async function loadTemplate(name: string) {
197
  const templatePath = await resolver.resolvePath(`./templates/${name}`, {
198
    extensions: [".vue", ".ts", ".js"]
199
  });
200
  return templatePath;
201
}
202
```
203

204
### Module Resolution
205

206
Specialized utilities for resolving Nuxt modules and dependencies.
207

208
```typescript { .api }
209
/**
210
 * Resolve Nuxt module paths
211
 * @param base - Base directory for resolution
212
 * @param paths - Module paths to resolve
213
 * @returns Promise resolving to array of resolved module paths
214
 */
215
function resolveNuxtModule(base: string, paths: string[]): Promise<string[]>;
216

217
/**
218
 * Try to resolve a module from given URLs/paths
219
 * @param id - Module identifier to resolve
220
 * @param url - URL or array of URLs to resolve from
221
 * @returns Promise resolving to resolved path or undefined if not found
222
 */
223
function tryResolveModule(id: string, url: URL | URL[]): Promise<string | undefined>;
224
function tryResolveModule(id: string, url: string | string[]): Promise<string | undefined>;
225

226
/**
227
 * Resolve a module using standard Node.js resolution
228
 * @param id - Module identifier to resolve
229
 * @param options - Resolution options
230
 * @returns Resolved module path
231
 */
232
function resolveModule(id: string, options?: ResolveModuleOptions): string;
233

234
/**
235
 * Import a module dynamically with automatic de-defaulting
236
 * @param id - Module identifier to import
237
 * @param opts - Import options
238
 * @returns Promise resolving to imported module
239
 */
240
function importModule<T = unknown>(id: string, opts?: ImportModuleOptions): Promise<T>;
241

242
/**
243
 * Try to import a module, returning undefined if it fails
244
 * @param id - Module identifier to import
245
 * @param opts - Import options
246
 * @returns Promise resolving to imported module or undefined
247
 */
248
function tryImportModule<T = unknown>(id: string, opts?: ImportModuleOptions): Promise<T | undefined>;
249

250
/**
251
 * Require a module synchronously (deprecated - use importModule instead)
252
 * @deprecated Please use `importModule` instead
253
 * @param id - Module identifier to require
254
 * @param opts - Import options
255
 * @returns Required module
256
 */
257
function requireModule<T = unknown>(id: string, opts?: ImportModuleOptions): T;
258

259
/**
260
 * Try to require a module synchronously (deprecated - use tryImportModule instead)
261
 * @deprecated Please use `tryImportModule` instead
262
 * @param id - Module identifier to require
263
 * @param opts - Import options
264
 * @returns Required module or undefined if it fails
265
 */
266
function tryRequireModule<T = unknown>(id: string, opts?: ImportModuleOptions): T | undefined;
267

268
interface ResolveModuleOptions {
269
  /** @deprecated use `url` with URLs pointing at a file - never a directory */
270
  paths?: string | string[];
271
  url?: URL | URL[];
272
}
273

274
interface ImportModuleOptions extends ResolveModuleOptions {
275
  /** Automatically de-default the result of requiring the module */
276
  interopDefault?: boolean;
277
}
278
```
279

280
**Usage Examples:**
281

282
```typescript
283
import { 
284
  resolveNuxtModule, 
285
  importModule, 
286
  tryImportModule, 
287
  tryResolveModule, 
288
  requireModule, 
289
  tryRequireModule 
290
} from "@nuxt/kit";
291

292
// Resolve module dependencies
293
const modulePaths = await resolveNuxtModule(process.cwd(), [
294
  "@nuxtjs/tailwindcss",
295
  "@pinia/nuxt",
296
  "nuxt-icon"
297
]);
298

299
console.log("Found modules:", modulePaths);
300

301
// Import module dynamically (preferred)
302
const lodash = await importModule("lodash");
303
console.log(lodash.camelCase("hello world"));
304

305
// Try to import module (returns undefined if fails)
306
const optionalModule = await tryImportModule("optional-dependency");
307
if (optionalModule) {
308
  // Use optional module
309
}
310

311
// Try to resolve module path
312
const modulePath = await tryResolveModule("my-module", import.meta.url);
313
if (modulePath) {
314
  console.log("Module found at:", modulePath);
315
}
316

317
// Deprecated: Use requireModule (shows deprecation warning)
318
try {
319
  const config = requireModule("./config.js");
320
} catch (error) {
321
  console.error("Failed to require config");
322
}
323

324
// Deprecated: Try to require module
325
const optionalConfig = tryRequireModule("./optional-config.js");
326
if (optionalConfig) {
327
  // Use config
328
}
329
```
330

331
### Ignore Pattern Integration
332

333
Path resolution that respects Nuxt ignore patterns and .nuxtignore files.
334

335
```typescript { .api }
336
/**
337
 * Check if path should be ignored based on .nuxtignore and patterns
338
 * @param pathname - Path to check
339
 * @param stats - Optional file stats
340
 * @param nuxt - Nuxt instance (defaults to current context)
341
 * @returns True if path should be ignored
342
 */
343
function isIgnored(
344
  pathname: string,
345
  stats?: unknown,
346
  nuxt?: Nuxt
347
): boolean;
348

349
/**
350
 * Create ignore function with Nuxt context
351
 * @param nuxt - Nuxt instance (defaults to current context)
352
 * @returns Function to check if path should be ignored
353
 */
354
function createIsIgnored(nuxt?: Nuxt): (pathname: string, stats?: unknown) => boolean;
355

356
/**
357
 * Resolve ignore patterns from configuration and .nuxtignore
358
 * @param relativePath - Relative path for context
359
 * @returns Array of ignore patterns
360
 */
361
function resolveIgnorePatterns(relativePath?: string): string[];
362
```
363

364
**Usage Examples:**
365

366
```typescript
367
import { 
368
  isIgnored, 
369
  createIsIgnored, 
370
  resolveIgnorePatterns,
371
  resolveFiles 
372
} from "@nuxt/kit";
373

374
// Check if specific path is ignored
375
if (isIgnored("node_modules/package")) {
376
  console.log("Path is ignored");
377
}
378

379
// Create reusable ignore checker
380
const shouldIgnore = createIsIgnored();
381

382
const files = ["src/component.vue", "node_modules/lib.js", ".nuxt/dist"];
383
const validFiles = files.filter(file => !shouldIgnore(file));
384

385
// Get current ignore patterns
386
const patterns = resolveIgnorePatterns();
387
console.log("Ignore patterns:", patterns);
388

389
// Use with file resolution
390
const sourceFiles = await resolveFiles("~/src", "**/*", {
391
  ignore: resolveIgnorePatterns()
392
});
393
```
394

395
### Advanced Path Resolution Patterns
396

397
**Module-Relative Resolution:**
398

399
```typescript
400
import { createResolver, addComponent, addPlugin } from "@nuxt/kit";
401

402
export default defineNuxtModule({
403
  setup() {
404
    const resolver = createResolver(import.meta.url);
405
    
406
    // Resolve paths relative to module
407
    const runtimeDir = resolver.resolve("./runtime");
408
    const componentsDir = resolver.resolve("./components");
409
    
410
    // Use resolved paths
411
    addPlugin(resolver.resolve(runtimeDir, "plugin.mjs"));
412
    
413
    addComponent({
414
      name: "ModuleComponent",
415
      filePath: resolver.resolve(componentsDir, "Component.vue")
416
    });
417
  }
418
});
419
```
420

421
**Dynamic Path Resolution:**
422

423
```typescript
424
import { resolvePath, findPath } from "@nuxt/kit";
425

426
export default defineNuxtModule({
427
  async setup(options) {
428
    // Find user's preferred config format
429
    const configFile = await findPath([
430
      "my-module.config.ts",
431
      "my-module.config.js",
432
      "my-module.config.json"
433
    ]);
434
    
435
    if (configFile) {
436
      const config = await import(configFile);
437
      // Use config...
438
    }
439
    
440
    // Resolve theme files
441
    if (options.theme) {
442
      const themePath = await resolvePath(`~/themes/${options.theme}`);
443
      // Load theme...
444
    }
445
  }
446
});
447
```
448

449
## Types
450

451
```typescript { .api }
452
interface FileStats {
453
  isFile(): boolean;
454
  isDirectory(): boolean;
455
  size: number;
456
  mtime: Date;
457
  [key: string]: any;
458
}
459
```