ArchUnitTS

Architecture testing for TypeScript. Make architecture executable in the same test suite as your application. ArchUnitTS understands modern TypeScript configuration, detects cycles, enforces dependency direction, measures design health, and exports reports for humans and automation.

TypeScript & JavaScriptMIT

View repository ↗Documentation ↗

npm

npm install --save-dev archunit

architecture.test.ts

import { projectFiles } from 'archunit';

it('keeps the domain independent', async () => {
  const rule = projectFiles()
    .inFolder('src/domain/**')
    .shouldNot()
    .dependOnFiles()
    .inFolder('src/infrastructure/**');

  await expect(rule).toPassAsync();
});

Silent product demo

Watch architecture rules run in TypeScript.

This silent walkthrough follows ArchUnitTS from a fluent rule to the resulting test feedback. Playback starts muted, loops in place, and keeps standard controls available so you can inspect each step.

Watch on YouTube ↗

The ecosystem

TypeScript, in context.

TypeScript adds static types to JavaScript while keeping the same browser and Node.js runtime model. It powers frontend applications built with React, Angular, Vue, and similar frameworks, and it is equally at home in backends built with Express, Fastify, NestJS, and serverless platforms. That range makes explicit dependency boundaries especially valuable.

Typed JavaScript for browsers and Node.js

React, Angular, Vue, NestJS, Express, and Fastify

Well suited to monorepos and shared packages

Adoption snapshot

Public adoption, in context.

npm reports 1,013,805 downloads since the first retained package date, including 230,934 in the latest completed 30-day window.

View npm ↗Compare all libraries →

Package status: Published on npm
Reported history: 1,013,805
Latest 30 days: 230,934
GitHub stars: 500

Capabilities

What ArchUnitTS brings to the test suite.

The family shares a recognizable architecture vocabulary while each implementation stays honest about its language, toolchain, and maturity.

Cycle and dependency-direction rules

Layer, slice, Nx, and PlantUML policies

Cohesion, coupling, and distance metrics

Jest, Vitest, Jasmine, and runner-neutral APIs

HTML, Mermaid, D2, JSON, CSV, and DOT reports

Modern tsconfig paths and project references

Go deeper

Catch cycles before they become refactors.

A cycle rule scans the selected source graph and reports the complete dependency path. Keep it beside unit tests so a newly introduced loop fails the same pull request that created it.

cycles.test.ts

import { projectFiles } from 'archunit';

it('keeps production code cycle free', async () => {
  const rule = projectFiles()
    .inFolder('src/**')
    .should()
    .haveNoCycles();

  await expect(rule).toPassAsync();
});

Documentation highlights

Work with ArchUnitTS beyond the quickstart.

ArchUnitTS follows the TypeScript project your compiler already knows, then exposes focused rules, metrics, and graph reports through a fluent API. These are the parts most teams use after the first boundary test.

Select the code that carries the rule

Start from projectFiles(), then narrow the subject by filename, folder, or full path. String globs and regular expressions are supported, and repeated selectors narrow the same population.

withName() matches only the filename; inFolder() excludes the filename; inPath() sees the complete project-relative path.
The extractor reads tsconfig include and exclude settings, path aliases, and referenced projects instead of inventing a second project model.
Jest, Vitest, Jasmine, and runner-neutral check() calls all execute the same Checkable rule.

Move from imports to architecture

Rules can prohibit a dependency direction, detect circular imports, name layers, cut the project into slices, or compare the graph with a PlantUML component diagram.

Cycle checks operate on internal edges and report the complete dependency path that closes each loop.
Graph queries can focus on a pattern, follow reachable dependencies, find dependants, or collapse nodes to a folder depth.
DOT, Mermaid, D2, CSV, JSON, and standalone HTML render the same graph snapshot for different review workflows.

Measure pressure, not just breakage

The metrics API adds file size, declarations, cohesion, coupling, instability, and distance-from-main-sequence constraints to binary dependency rules.

Count rules cover lines, statements, methods, fields, classes, interfaces, functions, and imports.
LCOM variants make class cohesion testable, while distance metrics expose abstractness and outgoing-versus-incoming coupling.
Custom predicates and custom metrics keep project-specific decisions inside the same reporting and test integration layer.

Read the complete documentation ↗

Release and compatibility

Published package

The most mature member of the family, published on npm with a stable fluent API and broad reporting support.

View on npm ↗

LanguageTypeScript

ReleasePublished package

RuntimeTypeScript & JavaScript

LicenseMIT

Where it fits

Put boundaries next to the code they protect.

Common starting points for ArchUnitTS include the following project shapes.

Frontend boundariesNode.js servicesNx monoreposClean architecture

More ecosystems

The same intent, expressed natively.

Explore sibling implementations and carry the architecture vocabulary across a polyglot system.

Make the first boundary executable.

Add one meaningful rule, run it with the existing tests, and grow the architecture suite as the system reveals where it needs protection.

Start with ArchUnitTS ↗