Import Boundaries

Import boundary rules enforce layered architecture so routes do not reach into database internals and apps do not import sibling deployables.

Recipe

Quick-reference recipe card - copy-paste ready.

npm install -D eslint-plugin-import-x

{
  rules: {
    "import-x/no-restricted-paths": [
      "error",
      {
        zones: [
          {
            target: "./src/routes",
            from: "./src/db",
            message: "Routes must call services, not db layer directly",
          },
        ],
      },
    ],
  },
}

When to reach for this:

• Monorepos with apps/ and packages/.
• Layered folders: routes → services → repositories.
• You need automated enforcement, not README diagrams alone.

Working Example

apps/orders-api/src/
  routes/
  services/
  repositories/
  db/

// eslint.config.js
import importX from "eslint-plugin-import-x";
 
export default [
  {
    plugins: { "import-x": importX },
    files: ["apps/orders-api/src/**/*.ts"],
    rules: {
      "import-x/no-restricted-paths": [
        "error",
        {
          zones: [
            {
              target: "./src/routes/**",
              from: "./src/db/**",
            },
            {
              target: "./src/routes/**",
              from: "./src/repositories/**",
              message: "Use services from routes",
            },
            {
              target: "./src/services/**",
              from: "./src/routes/**",
              message: "Services must not import routes",
            },
          ],
        },
      ],
      "import-x/no-extraneous-dependencies": [
        "error",
        { devDependencies: ["**/*.test.ts", "eslint.config.js"] },
      ],
    },
  },
];

// BAD: src/routes/orders.ts
import { pool } from "../db/pool.js"; // ESLint error
 
// GOOD: src/routes/orders.ts
import { createOrder } from "../services/orders.js";

What this demonstrates:

• no-restricted-paths blocks specific folder-to-folder imports.
• no-extraneous-dependencies stops phantom deps from hoisting.
• Messages document the intended architecture in CI failures.

Deep Dive

How It Works

• ESLint resolves import paths relative to the file being linted.
• Zones define target (importer glob) and from (forbidden source glob).
• Monorepos add zones preventing apps/a importing apps/b.
• Nx uses @nx/enforce-module-boundaries with tags for similar enforcement.

Monorepo Zone Example

{
  zones: [
    {
      target: "./apps/**",
      from: "./apps/**",
      except: ["./apps/shared-config"],
      message: "Apps import packages/, not other apps",
    },
  ],
}

TypeScript Notes

• Use .js extensions in import specifiers when "moduleResolution": "NodeNext".
• Boundary rules complement package.json exports - both should agree.

Gotchas

• Relative imports bypass package boundaries - ../../packages/foo/src. Fix: import @acme/foo package name only.
• Over-broad zones - Blocking legitimate shared test utilities. Fix: except globs for **/*.test.ts.
• Barrel files re-export everything - index.ts becomes a loophole. Fix: restrict barrels or lint public API surface with knip.
• False positives on path aliases - ESLint resolver not configured. Fix: import-x/resolver-typescript with projectService.
• Rules without CI - Developers skip locally. Fix: npm run lint required on PR.

Alternatives

FAQs

Related

• Linting Basics - flat config setup
• Nx for Node Backends - tag-based boundaries
• Multi-Service Monorepo - app vs package rules

External Related Links

• Node.js Best Practices (GitHub) - Curated production best practices.
• npm Official Website & Registry - Package search, publishing, and documentation.
• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js Design Patterns, 2nd Edition - Earlier edition still useful.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.