I built a linter that enforces Clean Architecture rules in TypeScript

#node #webdev #opensource #typescript

The problem

In every TypeScript codebase I've worked on, the same violation appears eventually:

// controllers/orderController.ts
import { OrderRepository } from '../repositories/orderRepository'; // ❌

A controller importing a repository directly. The service layer completely bypassed.

ESLint can't catch this - it has no concept of architectural layers. Code reviews catch it sometimes, but not always. And the bugs it causes are subtle.

So I built architecture-linter.

How it works

You create a .context.yml in your project root:

architecture:
  layers:
    - controller
    - service
    - repository

rules:
  controller:
    cannot_import:
      - repository

Then run:

npx architecture-linter scan

Output:

❌ Architecture violation detected

   File:   controllers/orderController.ts
   Import: repositories/orderRepository
   Rule:   Controller cannot import Repository

Found 1 violation in 3 file(s) scanned.

Setup takes 2 minutes

npm install --save-dev architecture-linter
npx architecture-linter init   # auto-detects your framework and layers
npx architecture-linter scan

init automatically detects NestJS and Next.js from your package.json and generates the right config - including file-suffix scanning (.controller.ts, .service.ts, etc.) for NestJS projects. Pass --force to overwrite an existing config.

Three ways to use it

1. CLI - run locally or in any CI pipeline

2. VS Code extension - violations appear as red squiggles in real time, with fix hints in the Problems panel

3. GitHub Action - annotates PRs with inline violations on the exact line

- uses: cvalingam/architecture-linter@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

Built-in presets

No need to write rules from scratch. Use a preset:

extends: nestjs   # or clean-architecture, hexagonal, nextjs

Available presets: nestjs, clean-architecture, hexagonal, nextjs

DEV Community