Aliases

Importing non-JS resources through stable, unversioned URLs.

While the import map handles JavaScript specifier resolution, you may need to reference package files directly by URL — for example, CSS files, images, or other assets. Because package directories include version numbers (e.g. client_modules/open-props@2.0.4/), these URLs break every time a dependency is updated.

The alias option solves this by creating unversioned symlinks alongside the versioned directories. For example, client_modules/open-props will point to client_modules/open-props@2.0.4.

This lets you use stable paths like client_modules/open-props/open-props.min.css in your HTML and CSS.

By default, alias is true, which creates an unversioned symlink for every copied package using its install name (generally the same as the package name, except for npm aliases). Set alias: false to opt out entirely.

Values

• true — alias the package at its install name. Only the copy whose version sits closest to the root is aliased, so duplicates at other versions are skipped.
• false — no alias.
• A string — a custom alias path, relative to the package’s dir. It may escape dir: "../open-props" places the alias at the project root, so <link href="open-props/open-props.min.css"> works from your HTML.

Scope values to packages via override rules:

export default {
	overrides: {
		"open-props": { alias: "../open-props" }, // alias at the project root
		"tailwindcss": { alias: "tw" },           // custom name inside dir
		"lodash": { alias: false },               // no alias for this one
	},
};

Rules take a regex matcher, so you can scope aliases to a whole namespace:

export default {
	overrides: [{ name: /^@vue\//, alias: false }], // no aliases for @vue/* internals
};

When an alias is removed from the config (or its package is uninstalled), the symlink is automatically cleaned up on the next run — including aliases outside dir.