Node.js (TypeScript) — "Max Power" Hexagonal Backend
AI Context & Token Optimization
- Interfaces as Ports: TypeScript
interfaceis the port. The AI reads one interface file and knows the entire contract — no implementation archaeology. - Strict Mode Always:
strict: trueintsconfig.json.anyis banned in core and application layers;unknown+ narrowing at adapter edges. - Constructor Injection: Explicit constructor parameters over service locators. Missing dependencies fail at composition time, not in production.
Project Structure
project-root/
├── src/
│ ├── core/
│ │ ├── domain/ # Pure entities (no imports from outside core)
│ │ └── ports/
│ │ ├── inbound/ # Primary ports (e.g., UserService)
│ │ └── outbound/ # Secondary ports (e.g., UserRepository, Clock)
│ ├── application/ # Use cases implementing inbound ports
│ │ └── create-user.ts
│ ├── adapters/
│ │ ├── inbound/
│ │ │ └── http/ # Route handlers (Fastify/Express/Hono)
│ │ └── outbound/
│ │ ├── postgres/ # Prisma/TypeORM repository implementations
│ │ └── cache/ # Redis adapter
│ ├── di/
│ │ └── container.ts # Composition root (tsyringe or manual wiring)
│ └── main.ts # Entry point, builds container, starts server
├── prisma/
│ └── schema.prisma # Schema source of truth (see database-migration)
├── package.json
└── tsconfig.json # strict: true
Naming Conventions
| Artifact | Convention | Example |
|---|---|---|
| Port interfaces | Nouns (*Repository) or role er nouns |
UserRepository, UserCreator |
| Use cases | Verb + entity | CreateUser, ArchiveOrder |
| Files | kebab-case.ts |
create-user.ts |
| DTOs | *Dto with zod/class-validator |
CreateUserDto |
Architectural Patterns
Zero-Framework Core: src/core imports NOTHING from frameworks (no http lib, no ORM, no validation lib in entities). Violation fails review.
Dependency Direction: adapters depend on core ports; core never imports adapters. Import-lint rule or review checklist enforces it.
DTOs at the Edge: validate at inbound adapters (zod schemas), map to domain entities immediately. Never leak ORM models through ports.
Clock Abstraction: Clock port (now(): Date) in core/ports/outbound. Banned: new Date() in domain/application code — inject the clock.
Universal DateTime Governance
- UTC at rest: store ISO-8601 UTC strings or epoch ms. Banned: locale-formatted date strings in storage/cache.
- Transmit: ISO-8601 with offset or epoch ms, matching the API contract.
Testing Strategies
| Layer | Test Type | Framework / Tools |
|---|---|---|
| Application | Unit | vitest + in-memory port fakes |
| Adapters | Integration | vitest + testcontainers (real PG/Redis) |
- Write table-driven (
it.each) tests for all use cases against faked outbound ports. - Inbound HTTP routes tested via supertest-style injection with the real container and faked repositories.
Strict Tooling Gate (Machine-Enforced — Forced Strict Mode)
Strictest verified toolchain for this stack. Load this skill whenever the project matches the stack. Execute the gate in fail-fast order and stop on the first failure. Record the exact command, output, and exit code in the task's Verification Evidence.
Strict Baseline
Target: Node.js + TypeScript backend organized as Hexagonal Architecture (Ports and Adapters). All versions verified live against the npm registry / project release pages in 2025-2026. Pinned to the strictest maintained tool for each role. Deprecated or dormant tools are called out explicitly and excluded from the mandatory chain.
Required Toolchain
| Tool | Purpose | Minimum version | Activate |
|---|---|---|---|
| Node.js | Runtime; LTS only | 24.0.0 (24.x Active LTS "Krypton") | .nvmrc → 24 ; package.json → "engines": { "node": ">=24.0.0" } |
| TypeScript | tsc --noEmit type gate + parser backend for typed lint |
6.0.3 | npm i -D typescript@6.0.3 |
| @typescript/native-preview (optional) | TS7 tsgo fast type-check alongside TS6; TS7 has no programmatic API yet so typed-lint tools cannot use it |
7.0.2 | npm i -D @typescript/native-preview@^7 (run via tsgo --noEmit only) |
| ESLint | Core linter, flat config only (eslintrc deleted in v10) | 10.0.0 (10.4.x) | npm i -D eslint@^10 @eslint/js@^10 |
| typescript-eslint | Type-aware rule engine (strictTypeChecked, stylisticTypeChecked) |
8.70.1 | npm i -D typescript-eslint@^8 |
| eslint-plugin-n | Node correctness (no-process-exit, no-missing-import, deprecation) |
18.2.2 | npm i -D eslint-plugin-n@^18 |
| dependency-cruiser | Primary architectural boundary + cycle enforcement on the real resolved graph | 18.4.0 | npm i -D dependency-cruiser@^18.4 |
| eslint-plugin-boundaries | Secondary, in-editor boundary feedback (import-time, entity model v7) | 7.2.0 | npm i -D eslint-plugin-boundaries@^7 |
| eslint-plugin-import-x (optional) | Fast per-file no-restricted-paths guard; maintained fork (ESLint 10 ready) |
4.16.2 | npm i -D eslint-plugin-import-x@^4 |
| Vitest + @vitest/coverage-v8 | Unit / contract / property runner with fail-on-threshold coverage | 4.1.9 | npm i -D vitest@^4 @vitest/coverage-v8@^4 |
| testcontainers | Real infra in contract tests (Postgres, Redis, broker) | 12.1.0 | npm i -D testcontainers@^12 |
| fast-check | Property-based tests for core invariants | 4.9.0 | npm i -D fast-check@^4 |
| tsd | Type-level tests (expectType / expectError) |
0.33.0 | npm i -D tsd@^0.33 |
| @microsoft/api-extractor | Public API surface + declaration-diff gate | 7.59.1 | npm i -D @microsoft/api-extractor@^7 |
| publint | Package exports / publish-metadata gate |
0.3.24 | npm i -D publint@^0.3 |
| @arethetypeswrong/cli | Consumer-side .d.ts / module-resolution gate |
0.18.5 | npm i -D @arethetypeswrong/cli@^0.18 |
| knip | Unused files, exports, and dependencies | 6.4.1 | npm i -D knip@^6 |
| lockfile-lint | Lockfile host/integrity policy (anti-typosquat/injection) | 5.0.1 | npm i -D lockfile-lint@^5 |
| osv-scanner | Vulnerability scan against OSV (replaces/augments npm audit) |
2.5.1 | go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest or the official GH Action / binary |
| zod (or valibot) | Strict boot-time environment schema | 4.5.4 (valibot 1.4.2) | npm i zod@^4 |
Discarded / demoted (say so, do not silently use):
- madge — cycle/graph tool, but last npm release is 8.0.0, Aug 2024 (dormant ~2 years, download trend falling). Its only irreplaceable role, cycle detection, is already covered by dependency-cruiser's
no-circularrule (actively maintained, minimum 18.4.0 — the$1backreference used below was validated on 18.4). Keep madge only for one-off visual graphs, never as a gate. - depcheck — superseded by knip (knip covers files + exports + dependencies and is actively maintained; depcheck 1.4.7 last shipped Aug 2025 and is narrower).
- eslint-plugin-import — effectively frozen/refuses
exports/specifier support; the maintained successor is eslint-plugin-import-x, which declares ESLint^8.57 || ^9 || ^10. - TypeScript 7.x as the typed-linting backend — 7.0.2 is npm
latest, buttypescript-eslintsupports only>=4.8.4 <6.1.0; pointingtypescriptat 7 makes typed lint crash (ts.Extension.Cjsundefined). Pintypescript@6.0.3for lint; run TS7 side-by-side viatsgofor speed only.
Strict Baseline Config
tsconfig.json — every strict flag, tsc --noEmit is the gate:
{
"compilerOptions": {
"target": "es2024",
"lib": ["es2024"],
"module": "nodenext",
"moduleResolution": "nodenext",
"moduleDetection": "force",
"types": ["node"],
"rootDir": "./src",
"outDir": "./dist",
/* maximum static strictness */
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitOverride": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"noImplicitThis": true,
"useUnknownInCatchVariables": true,
"noPropertyAccessFromIndexSignature": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"allowUnreachableCode": false,
"allowUnusedLabels": false,
"forceConsistentCasingInFileNames": true,
/* module purity */
"verbatimModuleSyntax": true,
"isolatedModules": true,
"noUncheckedSideEffectImports": true,
"erasableSyntaxOnly": true,
/* emit for libs; keep type-check honest */
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"skipLibCheck": false
},
"include": ["src"],
"exclude": ["dist", "node_modules"]
}
eslint.config.mjs — ESLint 10 flat config, strictest type-checked presets:
// @ts-check
import js from '@eslint/js';
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';
import node from 'eslint-plugin-n';
export default defineConfig(
{ ignores: ['dist/**', 'coverage/**', 'node_modules/**', '**/*.d.ts'] },
js.configs.recommended,
...tseslint.configs.strictTypeChecked,
...tseslint.configs.stylisticTypeChecked,
{
files: ['**/*.{ts,mts,cts}'],
languageOptions: {
parserOptions: {
projectService: true, // typed linting; no tsconfig.eslint.json
tsconfigRootDir: import.meta.dirname,
},
},
rules: {
'@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],
'@typescript-eslint/no-misused-promises': ['error', {
checksConditionals: true,
checksSpreads: true,
checksVoidReturn: { arguments: true, attributes: false, returns: true },
}],
'@typescript-eslint/switch-exhaustiveness-check': ['error', {
considerDefaultExhaustiveForUnions: true,
requireDefaultForNonUnion: true,
}],
'@typescript-eslint/consistent-type-imports': ['error', { prefer: 'type-imports', fixStyle: 'inline-type-imports' }],
'@typescript-eslint/no-import-type-side-effects': 'error',
'@typescript-eslint/explicit-function-return-type': ['error', { allowExpressions: false }],
'@typescript-eslint/no-explicit-any': 'error',
},
},
node.configs["flat/recommended-module"],
);
.dependency-cruiser.cjs — the boundary gate (copy-paste; layout src/core, src/adapters, src/shared, src/composition):
/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
forbidden: [
{
name: 'no-circular',
severity: 'error',
comment: 'No dependency cycles anywhere.',
from: {},
to: { circular: true },
},
{
name: 'core-no-runtime-deps',
severity: 'error',
comment: 'domain+ports (the hexagon) must have ZERO npm runtime dependencies.',
from: { path: '^src/core/' },
to: { dependencyTypes: ['npm'], pathNot: '^src/core/' },
},
{
name: 'core-no-node-builtins',
severity: 'error',
comment: 'domain+ports must not touch Node builtins (fs/net/http/crypto).',
from: { path: '^src/core/' },
to: { dependencyTypes: ['core'] },
},
{
name: 'core-no-outward',
severity: 'error',
comment: 'core must never import adapters, shared infra, or the composition root.',
from: { path: '^src/core/' },
to: { path: '^src/(adapters|shared|composition)/' },
},
{
name: 'no-cross-adapter',
severity: 'error',
comment: 'adapters must not import each other; collaborate through core ports.',
from: { path: '^src/adapters/([^/]+)/' },
to: { path: '^src/adapters/([^/]+)/', pathNot: '^src/adapters/$1/' }, // $1 validated on 18.4
},
{
name: 'adapters-inward-only',
severity: 'error',
comment: 'adapters may import core/shared/their own folder only — never the composition root.',
from: { path: '^src/adapters/' },
to: { path: '^src/(?!core/|adapters/|shared/)' },
},
{
name: 'shared-no-outward',
severity: 'error',
comment: 'shared infra must not depend on core, adapters, or composition.',
from: { path: '^src/shared/' },
to: { path: '^src/(core|adapters|composition)/' },
},
{
name: 'no-orphans',
severity: 'error',
comment: 'unreferenced modules are dead code.',
from: { orphan: true, pathNot: ['\\.d\\.ts$', '\\.test\\.ts$', '\\.spec\\.ts$', '^src/composition/'] },
to: {},
},
],
options: {
tsConfig: { fileName: 'tsconfig.json' }, // resolves tsconfig paths + aliases
tsPreCompilationDeps: true,
doNotFollow: { path: 'node_modules' },
enhancedResolveOptions: { exportsFields: ['exports'], conditionNames: ['import', 'require', 'node', 'default'] },
exclude: { path: ['\\.test\\.ts$', '\\.spec\\.ts$', '\\.config\\.(ts|js|mjs|cjs)$', '^dist/'] },
includeOnly: { path: '^src/' },
},
};
knip.json — dead code / dependency hygiene:
{
"$schema": "https://unpkg.com/knip@6/schema.json",
"entry": ["src/composition/main.ts"],
"project": ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/*.spec.ts"],
"ignoreExportsUsedInFile": true
}
vitest.config.ts — coverage thresholds are the gate (Vitest 4 requires coverage.include; coverage.all was removed):
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'node',
include: ['src/**/*.test.ts', 'test/**/*.test.ts'],
coverage: {
provider: 'v8',
reporter: ['text', 'json-summary'],
include: ['src/core/**/*.ts', 'src/adapters/**/*.ts'],
thresholds: {
lines: 100,
functions: 100,
branches: 100,
statements: 100,
perFile: true, // every file, not just aggregate
'src/core/**': { branches: 100, functions: 100, lines: 100, statements: 100 }, // the hexagon is fully covered
},
},
},
});
Boot-time env schema (fails the process before the server listens; unit-tested):
// src/composition/config.ts
import { z } from 'zod';
const Env = z.object({
NODE_ENV: z.enum(['development', 'test', 'production']),
PORT: z.coerce.number().int().positive(),
DATABASE_URL: z.string().url(),
});
export type Config = z.infer<typeof Env>;
export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => Env.parse(env);
package.json scripts — the single gate chain:
{
"type": "module",
"engines": { "node": ">=24.0.0" },
"scripts": {
"verify": "npm run typecheck && npm run lint && npm run arch && npm run deadcode && npm run test && npm run types && npm run package"
}
}
Mandatory Gate Order
npm ci --ignore-scripts(npm 12 already blocks dependency install scripts;--ignore-scriptsmakes it explicit and works on npm 11)npx lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-httpsosv-scanner scan source -r . --licensesnpx tsc --noEmitnpx eslint . --max-warnings=0npx depcruise src --config .dependency-cruiser.cjsnpx knip --productionnpx vitest run --coveragenpx tsdnpx publint && npx attw --pack .(only when the package is published)npx api-extractor run --local(only when a.api.mdsurface is maintained)
Run in order, stop on the first non-zero exit. Warnings are errors; do not auto-fix in CI. (
eslintis invoked WITHOUT--fix;--max-warnings=0makes any warning fatal.)
Hallucination Traps to Block
- Domain/core importing an ORM or web framework (Prisma, TypeORM, Express, NestJS) →
dependency-cruisercore-no-runtime-deps(blocks everydependencyTypes: ["npm"]edge intosrc/core/). - Adapter A importing adapter B directly instead of via a port →
dependency-cruiserno-cross-adaptergroup-capture rule ($1matching). - Floating / unawaited promise in an async handler silently swallowing failures →
@typescript-eslint/no-floating-promises. - Async function passed where a
void-returning callback is expected (event emitters,setTimeout,forEach) →@typescript-eslint/no-misused-promises(checksVoidReturn). - New union member added but a
switchnot updated →@typescript-eslint/switch-exhaustiveness-check(requireDefaultForNonUnion). process.exit()bypassing graceful shutdown (in-flight requests dropped) →eslint-plugin-nn/no-process-exit.- Reading
process.env.Xdirectly (unvalidated/possiblyundefined) →zod/valibotboot schema +noPropertyAccessFromIndexSignature+noUncheckedIndexedAccess+useUnknownInCatchVariables. - Dead adapter / unused export left behind after a refactor →
knip(files, exports, dependencies). anyleaking throughcatchor library boundaries →strictTypeChecked(no-unsafe-*) +@typescript-eslint/no-explicit-any.- Broken
exports/.d.tsfor consumers despite green local tests →publint+@arethetypeswrong/cli. - Supply-chain code execution at install time (Shai-Hulud-class) →
npm ci --ignore-scripts+lockfile-lint+osv-scanner.
Evidence to Record
Paste the exact command and its pass signal into Verification Evidence; all must exit 0.
npx tsc --noEmit→ exit0, no output.npx eslint . --max-warnings=0→ exit0, summary0 problems.npx depcruise src --config .dependency-cruiser.cjs→ exit0, outputno dependency violations found.npx knip --production→ exit0, no unused files/exports/dependencies listed.npx vitest run --coverage→ exit0, every threshold line reports>= 100andTest Filesall passed.npx tsd→ exit0, no type assertion failures.npx publint && npx attw --pack .→ exit0(publint: no errors; attw: all resolution modes🟢).npx lockfile-lint ... && osv-scanner scan source -r . --licenses→ exit0, noallowed-hostsviolations and no HIGH/CRITICAL advisories.- Unit-only core test proof:
npx vitest run src/coreexits0with notestcontainers/network started (core has no I/O). - Env failure proof:
node -e "import('./dist/composition/config.js').then(m=>m.loadConfig({}))" ; test $? -ne 0(missing vars must throw, not boot).
- https://typescript-eslint.io/users/configs/
- https://typescript-eslint.io/getting-started/typed-linting
- https://typescript-eslint.io/users/dependency-versions/
- https://github.com/typescript-eslint/typescript-eslint/issues/12518
- https://eslint.org/blog/2026/02/eslint-v10.0.0-released/
- https://eslint.org/docs/latest/use/migrate-to-10.0.0
- https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-9.html
- https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
- https://registry.npmjs.org/-/package/typescript/dist-tags
- https://github.com/eslint-community/eslint-plugin-n
- https://github.com/sverweij/dependency-cruiser
- https://github.com/sverweij/dependency-cruiser/blob/HEAD/doc/rules-reference.md
- https://github.com/sverweij/dependency-cruiser/blob/HEAD/doc/options-reference.md
- https://github.com/javierbrea/eslint-plugin-boundaries
- https://github.com/javierbrea/eslint-plugin-boundaries/releases/tag/v7.0.0
- https://github.com/un-ts/eslint-plugin-import-x
- https://github.com/un-ts/eslint-plugin-import-x/blob/master/docs/rules/no-restricted-paths.md
- https://vitest.dev/config/coverage
- https://vitest.dev/guide/migration/
- https://github.com/testcontainers/testcontainers-node/releases
- https://fast-check.dev/
- https://knip.dev/reference/configuration
- https://knip.dev/guides/configuring-project-files
- https://github.com/lirantal/lockfile-lint
- https://google.github.io/osv-scanner/supported-languages-and-lockfiles/
- https://github.com/google/osv-scanner/releases
- https://github.com/tsdjs/tsd
- https://www.npmjs.com/package/@microsoft/api-extractor
- https://www.pkgpulse.com/guides/publint-vs-arethetypeswrong-vs-knip-2026
- https://www.pkgpulse.com/guides/publint-vs-arethetypeswrong-vs-pkg-pr-new-package-quality-2026
- https://www.npmjs.com/package/dependency-cruiser
- https://www.npmjs.com/package/eslint-plugin-boundaries
- https://www.npmjs.com/package/eslint-plugin-n
- https://www.npmjs.com/package/madge
- https://www.npmjs.com/package/depcheck
- https://www.npmjs.com/package/lockfile-lint
- https://www.npmjs.com/package/zod
- https://www.npmjs.com/package/valibot
- https://www.npmjs.com/package/knip
- https://cve.optibot.re/blog/nodejs-24-lts-security-guide-2026
- https://github.com/nodejs/Release/issues/1161
- https://www.michal-drozd.com/en/blog/architectural-linting/
- https://github.com/fusic-toybox/architecture-as-steering
- https://docs.synapsestudios.com/implementation/frameworks/nest/dependency-cruiser-config
- https://github.com/zpratt/lousy-agents/blob/main/.dependency-cruiser.cjs
Currency Baseline
- Runtime: Node 22 LTS. Package manager:
pnpm(fallbacknpm). Validation:zod. ORM:prisma(migrations viaprisma migrate, neverdb pushon shared DBs).