Skip to content

ddd-ts-kit/imports-alias-only

Architecture id: imports/alias-only. Default severity: error in recommended, error in strict. Fixable (eslint --fix).

Applies to: every TypeScript file under the source root, under test/ and under scripts/.

An alias names a file from the root of the project. The import reads the same from every file, says which context and which layer it reaches without counting ../, and does not change when the importing file moves. One spelling also means one thing to review: the layer and context rules of this plugin, ddd-ts-kit check and dependency-cruiser resolve an alias exactly as they resolve a relative path, so a boundary is never crossed by choosing the other spelling.

The alias is declared once, under paths in tsconfig.json, which the compiler and the tools read. Node reads no alias: ddd-ts-kit build-aliases, the second step of npm run build, rewrites each alias of the compiled output into a relative path, so the output runs with plain node: no loader, no runtime dependency. See Import aliases.

  • a relative specifier, ./x or ../x, with or without an extension, the same directory included: fixed to the alias of the file (but between two files directly under test/support/, see Details)
  • a relative specifier that names a file under no aliased directory (a manifest, a build product): reported, not fixed
  • an alias specifier with a . or .. segment, which could name a file outside the directory of the alias: reported, not fixed

Incorrect:

src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
import { Invoice } from '../../../domain/aggregates/invoice.aggregate';
import { IssueInvoiceCommand } from './issue-invoice.command';
// test/e2e/issue-invoice.e2e.spec.ts
import { startApplication } from './support/start-application';

Correct:

src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command';
import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate';
// test/e2e/issue-invoice.e2e.spec.ts
import { startApplication } from '$test/e2e/support/start-application';

Static imports, type-only imports, export ... from, export *, dynamic import(), import() types and require() are all read. A dynamic import whose specifier is computed is not judged.

The aliases of a project:

Alias Directory Declared by
importAlias of ddd-ts-kit.config.json, @/ by default sourceRoot the config
$test/ test/ fixed
$scripts/ scripts/ fixed
$generated/ generated/, with stack.orm prisma only fixed

The fix computes the alias from the place of the file and the config: the relative specifier is resolved from the directory of the file, and the result is written from the directory its alias names, ending as importExtension of the config says: with nothing under none, with .js under js (a config without the key). It keeps the quotes of the specifier. A fixed import is often longer than the line: run the formatter after the fix (npm run format). Fixing twice changes nothing.

One relative path stands: a file directly under test/support/ imports its neighbour by ./<name>. A test runner loads its global setup, and every file that one imports, before any alias of the project exists: Jest applies no moduleNameMapper there, and a setup that imported by alias would load from the script of the project only, not from NODE_OPTIONS=--experimental-vm-modules npx jest nor from an editor. Nothing else is spared: from test/support/, ../e2e/support/start-application, ./parts/part, ./. and ./.. are reported, and so is ./parts when the disk holds a directory of that name and no parts.ts beside it; a file of any other directory imports its neighbour by alias.

The name of that neighbour is judged against the files on disk, and fixed. Under "importExtension": "none" a .ts source carries no extension (./test-database-run). Under "importExtension": "js" the neighbour is named by the name of its source: the runner loads the sources through its transform, which finds the file under the name it has. A ./test-database-run.js there passes the type check, then stops the run on Cannot find module: the fix writes ./test-database-run.ts, and ./esm.mts for ./esm.mjs, ./common.cts for ./common.cjs. A file that exists as it is named is not reported (a JSON file, a JavaScript file, an .mts source), nor is a name no source answers, which the compiler reports. A directory named as a neighbour is fixed to the alias of its index file under js ($test/support/parts/index.js), of the directory under none. The type check reads that ending with allowImportingTsExtensions and noEmit in tsconfig.json, both set back in tsconfig.build.json, which imports/alias-declared of ddd-ts-kit check holds. Whether ./parts is a directory is read on the disk when the file is linted; ddd-ts-kit check reads it from the files of the project.

test/support/test-database-setup.ts
import { openRun } from './test-database-run';

Not judged: a file outside the three directories (a config file at the project root, a JavaScript migration), the client under generated/, which a tool writes, and a specifier that is neither relative nor one of the aliases (a package, a Node built-in).

An alias that names no file is not this rule's concern: the compiler reports it (TS2307), and the build refuses it (ddd-ts-kit build-aliases).

None. sourceRoot and importAlias of ddd-ts-kit.config.json say what the alias of the sources is, importExtension what the fixed specifier ends with.

rules."imports/alias-only" in ddd-ts-kit.config.json set to off silences the rule, and // ddd-ts-kit-disable-next-line imports/alias-only -- <reason> silences one line, exactly as for ddd-ts-kit check.

  • Only a module the build emits can be named by the alias: a JSON file or another asset is read at run time instead of imported.
  • The ending of an alias specifier is the business of imports/extension.
  • The rule does not check that tsconfig.json declares the alias, nor that the build rewrites it: imports/alias-declared of ddd-ts-kit check does, with everything else that has to follow the one declaration.

ddd-ts-kit check reports the same id from the import specifiers it reads in the text of the files, under the source root, test/ and scripts/, and gives the alias to write in its fix sentence. This rule is the one that rewrites the import.