@rollup/plugin-alias

@rollup/plugin-alias lets a Rollup build treat one string as a stand-in for another module specifier, so import batman from '../../../batman' can become import batman from 'batman'. It mirrors the resolve.alias behavior familiar from Webpack: entries are declared as either a plain object map or an array of { find, replacement } pairs, checked in order, with find allowed to be a plain string prefix or a full regular expression for pattern-based rewrites (e.g. swapping file extensions across an entire import graph).

The plugin is intentionally small and hooks into exactly one place in Rollup’s pipeline: resolveId. When an importee matches an alias entry, it rewrites the id and either resolves it itself, defers to a custom resolver supplied per-entry or globally, or falls back to Rollup’s own this.resolve. That single-purpose design is what makes it composable — teams pair it with @rollup/plugin-node-resolve to alias short names to real filesystem paths, or with framework tooling (Vite, and other Rollup-based bundlers) that needs deterministic path rewriting without a full module-resolution algorithm of its own. It is maintained as one package inside the rollup/plugins monorepo, which houses the full family of official Rollup plugins.

What You Get

• Object or array syntax for declaring aliases, with array format supporting per-entry custom resolvers
• Regular-expression matching for partial replacements, such as rewriting file extensions across an entire import graph
• Order-sensitive matching — the first alias entry that matches an importee wins
• A customResolver hook (function or object with resolveId/buildStart) to delegate resolution to another plugin instead of Rollup’s default resolver
• Automatic fallback to Rollup’s built-in resolver via this.resolve with skipSelf: true when no custom resolver is supplied
• A build-time warning when a rewritten id isn’t absolute and wasn’t resolved by another plugin, flagging likely duplicate-module bugs early

Common Use Cases

• Replacing deep relative imports like ../../../utils with a flat alias such as utils across a large codebase
• Aliasing a versioned or renamed dependency (e.g. batman-1.0.0 to ./joker-1.5.0) during a migration without editing every import
• Using regex aliases to redirect all imports of one file extension to another, such as legacy AMD-style i18n! loader syntax to plain .js imports
• Combining with @rollup/plugin-node-resolve as the customResolver so aliased paths still go through Node’s module resolution algorithm

Under The Hood

Architecture The plugin implements a single Rollup resolveId hook and nothing else. Alias entries (object map or array form) are normalized up front by getEntries into a flat list of resolved alias records, each carrying its own resolver function when a custom resolver applies. On every resolution request, matches() checks the importee against each entry’s find value in declaration order — a string prefix/exact check or a regex test — and the first hit wins. A matched entry’s id is rewritten via string replace, then handed to a custom resolver if one exists, or resolved through Rollup’s own this.resolve with skipSelf: true, falling back to returning the rewritten id directly with a warning if it isn’t absolute and nothing else claimed it. The whole surface area is contained in one module, so the failure modes (an unmatched alias, an unresolved rewritten path) are easy to reason about end to end.

Tech Stack The package is authored in TypeScript, compiled with tsc, and ships as ESM-only (type: module, a single import export condition plus generated .d.ts types) — there’s no bundling step for the plugin itself. It sits inside the rollup/plugins pnpm workspace alongside the rest of the official plugin family, sharing a base tsconfig, ESLint config (eslint-config-rollup), and Prettier setup enforced repo-wide via Husky and lint-staged pre-commit hooks. Its only runtime dependency is Node’s own path module; Rollup itself is an optional peer dependency, and @rollup/plugin-node-resolve shows up only as a dev dependency used in tests and docs as the recommended customResolver pairing.

Code Quality Tests run under Vitest and exercise the plugin through actual Rollup builds rather than mocking the resolver pipeline — a small in-memory resolveId/load harness feeds real import graphs through rollup() and asserts on the resolved ids, covering object and array entry formats, regex aliases, and custom resolvers. Types are deliberately narrowed (a MapToFunction helper excludes the loose global Function type in favor of Rollup’s actual resolveId signature), which keeps the public RollupAliasOptions surface honest. Lint and type-check both run in CI (ci:lint, ci:test) ahead of publish, and unresolved-path situations surface as build warnings rather than being swallowed silently.

API Design The public API is intentionally minimal: one default export taking a single options object with just entries and an optional customResolver, closely mirroring Webpack’s familiar resolve.alias shape so the mental model transfers without new concepts to learn. Getting started requires no boilerplate beyond adding the plugin to a Rollup config’s plugins array. The tradeoff of that narrow surface is that it deliberately doesn’t try to out-innovate the well-established alias-resolution pattern it borrows from other bundlers — its value is in doing that one job simply and predictably.