Layerguard

Architectural layer enforcement for TypeScript and JavaScript projects.

Layerguard prevents architectural violations before they happen. Define your layers, declare how dependencies can flow between them, and Layerguard enforces those rules in CI, pre-commit hooks, or your editor.

Why Layerguard?

Catch violations early - Get instant feedback when code violates your architecture
Framework-agnostic - Works with Next.js, Vite, Angular, Node backends, and more
Fast incremental checking - Only re-checks files that changed
Zero runtime impact - Static analysis only, no runtime dependencies
Monorepo ready - First-class workspace support for pnpm, npm, and Yarn workspaces
ESLint integration - Inline editor feedback alongside your other linting rules

Installation

npm install --save-dev layerguard

Or with your preferred package manager:

pnpm add -D layerguard
yarn add -D layerguard

Requirements: Node.js 18.0.0 or higher, TypeScript 4.7.0 or higher

Quick Start

Run the interactive setup wizard:

npx layerguard init

The wizard detects your project structure, suggests layers, and generates layerguard.config.ts.

Then validate your architecture:

npx layerguard check

If code violates the rules:

layerguard check

  ✗ 1 violation

  ERROR  Layer violation: repository -> services
  src/repository/users.ts:3 -> src/services/auth.ts

  Repository cannot import from services.

Configuration

Create layerguard.config.ts in your project root:

import { defineConfig } from 'layerguard'

export default defineConfig({
  layers: {
    handlers:   { path: 'src/handlers/' },
    services:   { path: 'src/services/' },
    repository: { path: 'src/repository/' },
  },

  flow: [
    'handlers -> services',
    'services -> repository',
  ],
})

Layers

Each layer represents an architectural tier in your project:

layers: {
  // Layer name -> configuration
  pages:      { path: 'src/pages/' },
  components: { path: 'src/components/' },
  hooks:      { path: 'src/hooks/' },
  utils:      { path: 'src/utils/' },
}

Files within a layer directory belong to that layer. Files outside all layers are "unlayered" and can be handled via the unlayeredImports rule.

Flow Rules

Flow rules define allowed dependency directions:

flow: [
  'pages -> components',      // pages can import from components
  'pages -> hooks',           // pages can import from hooks
  'components -> hooks',      // components can import from hooks
  'hooks <-> utils',          // bidirectional: hooks and utils can import each other
]

A -> B - Unidirectional: A can import from B, but B cannot import from A
A <-> B - Bidirectional: A and B can import from each other

Any import not explicitly allowed is a violation.

Sublayers and Isolation

Layers can contain sublayers with their own rules:

layers: {
  components: {
    path: 'src/components/',
    sublayers: {
      features: { path: 'src/components/features/', isolated: true },
      shared:   { path: 'src/components/shared/' },
    },
    flow: ['features -> shared'],
  },
}

With isolated: true, sibling directories within the sublayer cannot import from each other. For example, features/auth/ cannot import from features/billing/.

Public API Enforcement

Restrict which files can be imported from outside a layer:

layers: {
  services: {
    path: 'src/services/',
    publicApi: 'index.ts',  // Only index.ts can be imported from outside
  },
}

Other files within the layer become private. This encourages clean module boundaries.

You can specify multiple public files:

publicApi: ['index.ts', 'types.ts']

Rules

Configure additional architectural checks:

rules: {
  // Circular dependency detection
  circular: 'error',           // 'error' | 'warn' | 'off' (default: 'error')

  // Orphan file detection (files not imported anywhere)
  orphans: 'warn',             // 'error' | 'warn' | 'off' (default: 'off')

  // Whether to enforce rules on type-only imports
  typeOnlyImports: 'ignore',   // 'enforce' | 'ignore' (default: 'ignore')

  // Imports from layered files to unlayered files
  unlayeredImports: 'warn',    // 'error' | 'warn' | 'ignore' (default: 'ignore')

  // How to resolve barrel re-exports
  barrelResolution: 'import-site',  // 'import-site' | 'origin' (default: 'import-site')

  // Workspace package import handling
  workspaceImports: 'ignore',  // 'enforce' | 'ignore' (default: 'ignore')

  // Maximum import chain depth (transitive imports)
  maxImportDepth: 5,           // Warns if exceeded

  // Maximum imports per file
  maxImportsPerFile: 20,       // Warns if exceeded
}

Barrel Resolution Modes:

import-site - Check against where the import points (e.g., services/index.ts)
origin - Trace re-exports to their source file (catches hidden violations through barrels)

Exceptions

Document exceptions when violations are intentional:

exceptions: [
  {
    from: 'src/repository/users.ts',
    to: 'src/services/auth.ts',
    reason: 'User repository needs auth service for password hashing',
  },
  {
    from: 'src/legacy/**/*.ts',
    to: 'src/**/*.ts',
    reason: 'Legacy code is being migrated gradually',
  },
]

Exceptions require a reason - this serves as living documentation for architectural decisions.

Ignore Patterns

Exclude files from analysis:

ignore: [
  '**/*.test.ts',
  '**/*.spec.ts',
  '**/mocks/**',
  '**/fixtures/**',
]

TypeScript Configuration

Specify custom tsconfig path(s):

// Single tsconfig
tsconfig: 'tsconfig.app.json',

// Multiple tsconfigs (merged)
tsconfig: ['tsconfig.app.json', 'tsconfig.server.json'],

CLI Commands

check

Validate architecture rules:

layerguard check [options]

Option	Description
`--ci`	Output in GitHub Actions annotation format
`--json`	Output violations as JSON
`--no-color`	Disable colored output
`--type-only`	Enforce rules on type-only imports
`--watch`, `-w`	Watch mode: re-check on file changes
`--no-cache`	Disable incremental caching
`--package`, `-p`	Check a specific workspace package
`--all`	Check all workspace packages
`--github-pr-comment`	Post results as a PR comment
`--pr-number`	PR number for comment (auto-detected in CI)

Examples:

layerguard check                     # Standard check
layerguard check --ci                # GitHub Actions annotations
layerguard check --json              # JSON output for tooling
layerguard check --watch             # Watch mode
layerguard check --package apps/web  # Check specific package
layerguard check --all               # Check all packages in monorepo

show

Display architecture diagram:

layerguard show [options]

Option	Description
`--ascii`	Use ASCII characters instead of Unicode
`--flow-only`	Show only flow rules, no diagram

init

Interactive setup wizard:

layerguard init [options]

Option	Description
`-y`, `--yes`	Skip prompts and use detected defaults

report

Generate HTML or Markdown report:

layerguard report [options]

Option	Description
`--output`, `-o`	Output file path (default: `layerguard-report.html`)
`--markdown`, `--md`	Output as Markdown instead of HTML
`--stdout`	Print to stdout instead of file
`--from`	Load historical data from JSON for trend charts
`--title`	Custom report title

Examples:

layerguard report                          # Generate HTML report
layerguard report --markdown               # Markdown summary
layerguard report -o reports/arch.html     # Custom output path
layerguard report --from history.json      # Include trend data

Monorepo Support

Layerguard detects pnpm, npm, and Yarn workspaces automatically.

Per-package Configuration

Each package can have its own layerguard.config.ts:

my-monorepo/
├── package.json          # workspaces: ["packages/*", "apps/*"]
├── packages/
│   └── shared/
│       └── layerguard.config.ts
└── apps/
    └── web/
        └── layerguard.config.ts

Check Specific Package

# By name
layerguard check --package @myorg/web

# By path
layerguard check --package apps/web

Check All Packages

layerguard check --all

This finds all packages with layerguard.config.ts and checks them in sequence.

Cross-package Imports

By default, workspace package imports (e.g., import { foo } from '@myorg/shared') are treated like external packages. Enable cross-package enforcement with:

rules: {
  workspaceImports: 'enforce',
}

Framework Support

Set framework to enable framework-specific intelligence:

export default defineConfig({
  framework: 'nextjs-app',
  // ...
})

Value	Framework
`nextjs-app`	Next.js App Router (`page.tsx`, `layout.tsx`, `route.ts`)
`nextjs-pages`	Next.js Pages Router (`_app.tsx`, `_document.tsx`)
`vite-react`	Vite + React (`main.tsx`, `vite.config.ts`)
`vite-react-router`	Vite + React Router file conventions
`vite-tanstack-router`	Vite + TanStack Router file conventions
`vue-nuxt`	Nuxt directory structure
`angular`	Angular module conventions
`node-backend`	Node.js backend patterns
`custom`	Manual configuration only

Framework detection enables:

Entry point recognition (excluded from orphan detection)
Framework-specific file patterns
Better layer suggestions in layerguard init

ESLint Integration

Get inline editor feedback with the ESLint plugin:

// eslint.config.js
import layerguard from 'layerguard/eslint'

export default [
  ...layerguard.configs.recommended,
  // your other config...
]

The plugin reads your layerguard.config.ts and reports violations as you type.

GitHub Actions

Add to your CI workflow:

name: Architecture Check

on: [push, pull_request]

jobs:
  layerguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx layerguard check --ci

The --ci flag outputs GitHub Actions annotations, showing violations inline in the PR diff.

PR Comments

Post a summary comment on pull requests:

- run: npx layerguard check --github-pr-comment
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This requires the gh CLI (pre-installed on GitHub-hosted runners).

VS Code Extension

Install the Layerguard extension for:

Inline diagnostics showing violations as you type
Quick fixes for common issues
Hover information showing layer relationships

Programmatic API

Use Layerguard programmatically in your tools:

import { loadConfig, validateConfig } from 'layerguard/config'
import { buildDependencyGraph } from 'layerguard/parser'
import { createFlowChecker } from 'layerguard/enforcer'

// Load and validate config
const { config } = await loadConfig(process.cwd())
const validation = validateConfig(config, process.cwd())

if (!validation.valid) {
  console.error(validation.errors)
  process.exit(1)
}

// Build dependency graph
const graph = buildDependencyGraph({
  projectRoot: process.cwd(),
  include: ['src/**/*.ts'],
})

// Check for violations
const checker = createFlowChecker(config)
const result = checker.checkGraph(graph)

console.log(`Found ${result.violations.length} violations`)

Exports

Export	Description
`layerguard`	Main entry point
`layerguard/config`	Config loading and validation
`layerguard/parser`	Dependency graph building
`layerguard/enforcer`	Violation checking
`layerguard/plugins`	Framework plugin interfaces
`layerguard/eslint`	ESLint plugin

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github		.github
bin		bin
src		src
tests		tests
vscode-extension		vscode-extension
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
archgate.config.ts		archgate.config.ts
eslint.config.ts		eslint.config.ts
layerguard.config.ts		layerguard.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Layerguard

Why Layerguard?

Table of Contents

Installation

Quick Start

Configuration

Layers

Flow Rules

Sublayers and Isolation

Public API Enforcement

Rules

Exceptions

Ignore Patterns

TypeScript Configuration

CLI Commands

check

show

init

report

Monorepo Support

Per-package Configuration

Check Specific Package

Check All Packages

Cross-package Imports

Framework Support

ESLint Integration

GitHub Actions

PR Comments

VS Code Extension

Programmatic API

Exports

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors

Uh oh!

Languages