@dads-framework/path-aliases
On this page
@dads-framework/path-aliases resolves the TypeScript paths aliases declared
by one explicit tsconfig — its own, or any it inherits through extends — to
absolute paths of files that exist. It reads through a file system port with
two providers: nodeFileSystem, which is the disk, and inMemoryFileSystem,
which is a map. Both are put through the same conformance suite.
What Dad does for you
Dad wants the resolution boundary written down where you can read it. You hand
him one tsconfig; every alias he honors comes from that file's paths, and an
alias shape he cannot honor exactly is a startup failure, not a quiet miss.
Try it
The npm install below is for the public release.
From an npm project on Node.js 22 or newer, install the resolver.
npm install @dads-framework/path-aliases
Save the following as resolve-alias.mts. The in-memory file system includes
both the tsconfig and its target, so the example needs no other files.
import { relative, resolve } from "node:path";
import {
createAliasResolver,
inMemoryFileSystem,
} from "@dads-framework/path-aliases";
const tsconfig = resolve("tsconfig.json");
const source = resolve("src/ui/button.ts");
const fileSystem = inMemoryFileSystem({
[tsconfig]: JSON.stringify({
compilerOptions: { paths: { "@app/*": ["./src/*"] } },
}),
[source]: 'export const label = "Save";',
});
const resolveAlias = createAliasResolver({ tsconfig, fileSystem });
const button = resolveAlias("@app/ui/button");
console.log(button && relative(".", button).split("\\").join("/"));
console.log(resolveAlias("react"));
node --experimental-strip-types resolve-alias.mts
The first line is src/ui/button.ts. The second is null because react
has no entry in the alias map. For an on-disk project, pass the path of your
tsconfig and nodeFileSystem to the same resolver.
For a disk-backed example, the repository's
domain boundaries fixture
maps @app/product-id to libraries/product-id/src/index.ts. Pass the
fixture's tsconfig.json and nodeFileSystem to resolve that import from
its declared alias.
Use it
| Export | What it is |
|---|---|
createAliasResolver({ tsconfig, fileSystem }) |
builds the resolver, and refuses every configuration it cannot honor |
AliasResolver |
(specifier: string) => string | null |
AliasFileSystem |
the port: isFile, readText, resolvePackage |
nodeFileSystem |
the provider over node:fs and node:module |
inMemoryFileSystem(files) |
the provider over a map of absolute paths to text |
runAliasResolverConformance({ root, fileSystem }) |
the suite every provider is run through; an empty finding list is passing |
aliasResolverConformanceLaws() |
the twenty-five law names the suite reports under, in run order |
AliasFileSystemFactory, AliasResolverConformanceSubject, AliasResolverConformanceFinding |
the shapes that suite takes and answers |
Aliases may be declared on the given tsconfig or inherited through its
extends chain, which may be a string or an array of strings and may name a
relative file or a package. The config that declares paths is the nearest one
in the chain; its targets resolve against the baseUrl of that config, or of
the nearest config after it that sets one, or against its own directory.
Resolution probes an alias target as a file, then as a package directory whose
entry point is the first of exports, module, and main that names an
existing file, then with each supported extension and as index.<extension>
inside it: .ts, .tsx, .js, .jsx, .json, .mts, .mjs, .cts,
.cjs, .css, .scss, and .less. A specifier written with an explicit
extension falls back to the matching source file, so @app/source.js finds
src/source.ts. A ?suffix query is stripped before matching.
exports contributes exports["."] when that is a string, otherwise its
import condition and then its default condition; any other exports shape,
an unreadable package.json, and no package.json at all leave module and
main to answer, and then the extension and index.<extension> probes.
What it refuses to do
- It does not load the TypeScript compiler. The tsconfig dialect — comments, trailing commas, and strings containing either — is read by this package, so your compiler version is yours to choose, or to skip.
- It does not touch a disk of its own. Every file question goes through the port, which is why the in-memory stand-in exists and why both providers run one suite.
- It does not discover a tsconfig. There is no search up the directory tree and no default: the config that owns resolution is the one you named.
- It does not guess at an alias shape it does not support. Two targets for
one alias, more than one
*, or a wildcard count that differs between pattern and target is a configuration-time error rather than a weaker match. - It does not claim a specifier it cannot prove. A bare specifier, an
absolute path, and an alias whose target names no existing file all answer
nulland stay the caller's to resolve. - It does not resolve every specifier under
baseUrl. An alias is honored becausepathsdeclares it, not because a file happens to sit beside the ones that are declared.
Contract
createAliasResolver(options: AliasResolverOptions): AliasResolver, where
AliasResolverOptions is { readonly tsconfig: string; readonly fileSystem: AliasFileSystem }. The resolver answers an absolute file path for a specifier
it owns and null for everything else.
Every failure below is thrown while the resolver is being built — configuration time, not resolve time — so a broken alias map fails the run instead of silently resolving less:
| Message | When |
|---|---|
Dads path aliases requires a non-empty tsconfig path. |
tsconfig is blank |
Dads path aliases tsconfig is not a readable file: <path> |
The named tsconfig is not a readable file |
Unable to read Dads path aliases tsconfig <path>: <detail> at line <l>, column <c> |
A config in the chain is unreadable or is not valid JSONC |
Dads path aliases tsconfig <path> does not declare or inherit compilerOptions.paths. |
No aliases were found |
Dads path alias <pattern> in <path> must have exactly one target. |
An alias maps to zero, several, or one unusable target |
Dads path alias <pattern> in <path> must use zero or one matching wildcard. |
Wildcards exceed one, or do not match |
Dads path aliases supports tsconfig extends only as a string or string array. |
extends is some other shape |
Dads path aliases cannot resolve tsconfig extends <target> from <path>. |
A relative extends names no file |
Dads path aliases cannot resolve tsconfig package <name> from <path>. |
A package extends cannot be resolved |
Dads path aliases found a circular tsconfig extends chain at <path>. |
The extends chain revisits a config |
runAliasResolverConformance answers a list of findings and throws nothing; an
empty list is conformance. Each finding names the case, the law, and what the
provider did instead. A subject is { root, fileSystem }, where root is an
absolute directory the suite builds its fixtures under and fileSystem builds
a provider serving exactly the files it is handed.
The package requires Node.js 22 or newer and has no dependencies at all.
Daddy issues this prevents
Alias resolution is where a build quietly stops matching the type checker: the compiler follows one map, the test runner follows another, and the disagreement only shows up as an import that works everywhere except in CI. One named config, one map, and a loud failure when it cannot be honored.