Aliased Asset Resolver

Design a small utility that resolves both JavaScript/TypeScript modules and CSS stylesheets from a project base directory using alias-aware resolution. The utility should surface resolved absolute paths, loaded contents, and dependency notifications so that build systems can track what was used.

Capabilities

Resolves aliased modules

• Resolves a specifier prefixed with a configured alias (e.g., @theme/) to an absolute module path under the mapped directory relative to base, loads the module exports, and returns them with the resolved path. @test
• Falls back to normal Node-style resolution for bare/relative specifiers when no alias matches, still returning the resolved absolute path and module exports. @test

Resolves aliased stylesheets

• Resolves a CSS specifier prefixed with a configured alias to an absolute stylesheet path under the mapped directory relative to base, loads the stylesheet contents, and returns them with the resolved path. @test

Collects dependencies

• Every successful module or stylesheet resolution triggers the optional onDependency callback exactly once with the resolved absolute path, regardless of whether it came from an alias match or the fallback resolver. @test

Implementation

@generates

API

export interface AliasMap {
  [aliasPrefix: string]: string;
}

export interface ResolveOptions {
  /** Base directory for resolution (e.g., project root) */
  base: string;
  /** Map of alias prefixes (like "@theme/") to directories relative to base */
  aliases: AliasMap;
  /** Optional callback fired once per resolved path */
  onDependency?: (path: string) => void;
}

export interface ResolvedModule<T = any> {
  path: string;
  exports: T;
}

/** Resolve a module specifier using alias and fallback resolution, returning exports and path */
export function loadModuleWithAliases<T = any>(specifier: string, options: ResolveOptions): Promise<ResolvedModule<T>>;

/** Resolve a stylesheet specifier using alias and fallback resolution, returning contents and path */
export function loadStylesheetWithAliases(specifier: string, options: ResolveOptions): Promise<{ path: string; css: string }>;

Dependencies { .dependencies }

@tailwindcss/node { .dependency }

Provides Node-aware module and stylesheet resolution with customizable resolvers and dependency tracking callbacks.