@winter-love/vite-plugin-monorepo-alias/dist/alias.d.ts

vite monorepo alias plugin

import { Plugin } from 'vite';
/**
 * Options for the monorepo alias plugin.
 */
export interface ResolveIdOptions {
    /**
     * Workspace-keyed alias map. Keys are workspace paths (e.g. `'packages/foo'`), values are
     * alias records (import specifier → resolution path). Use `'DEFAULT'` for fallback.
     * @example
     * {
     *   'DEFAULT': { 'src': 'src' },
     *   'apps/web': { '#utils': 'src/utils' }
     * }
     */
    alias?: Record<string, Record<string, string>>;
    /** Project root path. Defaults to `process.cwd()`. */
    root?: string;
    /** Path separator for normalization. Defaults to `path.sep`. */
    separator?: string;
    /** Paths or regexes that identify workspace roots (e.g. `['packages/']`). */
    workspacePaths?: (string | RegExp)[];
}
/**
 * Trims trailing backslashes or slashes and appends the replacer.
 * @param path - Path string to trim.
 * @param replacer - String to append after the trimmed path.
 * @returns Trimmed path ending with `replacer`.
 */
export declare const trimLastSlash: (path: string, replacer: string) => string;
/**
 * Trims leading backslashes or slashes and prepends the replacer.
 * @param path - Path string to trim.
 * @param replacer - String to prepend before the trimmed path.
 * @returns Trimmed path starting with `replacer`.
 */
export declare const trimFirstSlash: (path: string, replacer: string) => string;
/**
 * Builds a RegExp that matches a workspace path plus a package segment (e.g. `packages/foo/`).
 * @param workspacePath - Workspace path string (e.g. `'packages/'`).
 * @returns RegExp matching that path and a segment like `[-._a-zA-Z0-9]+`.
 */
export declare const getWorkspaceRegexString: (workspacePath: string) => RegExp;
/**
 * Converts a workspace path (string or RegExp) into the standard workspace regex.
 * @param workspacePath - Workspace path string or RegExp (only `source` is used).
 * @returns RegExp for matching that workspace path.
 */
export declare const getWorkspaceRegex: (workspacePath: string | RegExp) => RegExp;
/**
 * Builds a list of workspace regexes from path strings and/or RegExps.
 * @param workspacePaths - Array of workspace paths or RegExps.
 * @returns Array of RegExps for matching those workspace paths.
 */
export declare const getWorkspaceRegexList: (workspacePaths: (string | RegExp)[]) => RegExp[];
/**
 * Result of matching an absolute path against configured workspace paths.
 */
export interface MatchWorkspaceResult {
    /** Path relative to the matched workspace root. */
    relativePath: string;
    /** Matched workspace root segment (e.g. `'/packages/foo/'`). */
    relativeWorkspaceRoot: string;
    /** Project root path passed to `matchWorkspace`. */
    root: string;
    /** Absolute path of the matched workspace root. */
    workspaceRoot: string;
}
/**
 * Finds the first workspace that contains the given path. Order of `workspacePaths` matters.
 * @param root - Project root path.
 * @param workspacePaths - RegExps from `getWorkspaceRegexList`.
 * @param path - Normalized absolute path to test.
 * @returns Match result if the path is under a configured workspace, otherwise `undefined`.
 */
export declare const matchWorkspace: (root: string, workspacePaths: RegExp[], path: string) => MatchWorkspaceResult | undefined;
/**
 * Resolves a module id using the given alias list. First matching alias wins.
 * @param source - Import specifier (e.g. `'#utils/index'`).
 * @param alias - List of `[RegExp, replacement]` pairs (e.g. from `normalizeAlias`).
 * @returns Resolved path if a prefix matched, otherwise `source` unchanged.
 */
export declare const getAliasId: (source: string, alias?: [RegExp, string][]) => string;
/**
 * Turns an alias key into a RegExp that matches the key at the start of a string.
 * Metacharacters in the key are escaped so only the literal key matches.
 * @param path - Alias key (e.g. `'#utils'` or `'src/utils'`).
 * @returns RegExp matching `^${path}`.
 */
export declare const normalizeAliasKey: (path: string) => RegExp;
/**
 * Converts a flat alias map into a list of [RegExp, replacement] for use with `getAliasId`.
 * @param alias - Map of import prefix → resolution path.
 * @returns List of [RegExp, path] with keys normalized by `normalizeAliasKey`.
 */
export declare const normalizeAlias: (alias: Record<string, string>) => [RegExp, string][];
/**
 * Normalizes a workspace key to a slash-bounded form (e.g. `'/packages/foo/'`).
 * @param key - Workspace path key.
 * @returns Key with leading/trailing slashes normalized.
 */
export declare const normalizeAliasTreeKey: (key: string) => string;
/**
 * Converts a workspace-keyed alias tree into a tree of [RegExp, string][] values.
 * @param alias - Map of workspace path → alias map.
 * @returns Map of normalized workspace key → `normalizeAlias(alias[key])`.
 */
export declare const normalizeAliasTree: (alias: Record<string, Record<string, string>>) => {
    [k: string]: [RegExp, string][];
};
/**
 * Creates a Vite plugin that applies workspace-specific aliases in a monorepo.
 * Alias is only applied when the importer path matches one of `workspacePaths`.
 * @param options - Plugin options (root, workspacePaths, alias, separator).
 * @returns Vite plugin instance.
 */
export declare const createAlias: (options: ResolveIdOptions) => Plugin;
/** Alias for `createAlias`. */
export declare const monorepoAlias: (options: ResolveIdOptions) => Plugin;