Limites de Importação

Regras de limite de importação aplicam arquitetura em camadas para que rotas não alcancem os internos do banco de dados e aplicativos não importem implantáveis irmãos.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npm install -D eslint-plugin-import-x

{
  rules: {
    "import-x/no-restricted-paths": [
      "error",
      {
        zones: [
          {
            target: "./src/routes",
            from: "./src/db",
            message: "Rotas devem chamar serviços, não a camada de db diretamente",
          },
        ],
      },
    ],
  },
}

Quando usar isso:

• Monorepos com apps/ e packages/.
• Pastas em camadas: routes → services → repositories.
• Você precisa de aplicação automatizada, não apenas diagramas no README.

Exemplo de Trabalho

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 serviços a partir das rotas",
            },
            {
              target: "./src/services/**",
              from: "./src/routes/**",
              message: "Serviços não devem importar rotas",
            },
          ],
        },
      ],
      "import-x/no-extraneous-dependencies": [
        "error",
        { devDependencies: ["**/*.test.ts", "eslint.config.js"] },
      ],
    },
  },
];

// RUIM: src/routes/orders.ts
import { pool } from "../db/pool.js"; // Erro do ESLint
 
// BOM: src/routes/orders.ts
import { createOrder } from "../services/orders.js";

O que isso demonstra:

• no-restricted-paths bloqueia importações específicas de pasta para pasta.
• no-extraneous-dependencies impede que dependências fantasmas sejam elevadas.
• Mensagens documentam a arquitetura pretendida em falhas de CI.

Mergulho Profundo

Como Funciona

• O ESLint resolve caminhos de importação relativos ao arquivo que está sendo verificado.
• Zonas definem target (glob do importador) e from (glob da origem proibida).
• Monorepos adicionam zonas impedindo que apps/a importe apps/b.
• Nx usa @nx/enforce-module-boundaries com tags para aplicação semelhante.

Exemplo de Zona de Monorepo

{
  zones: [
    {
      target: "./apps/**",
      from: "./apps/**",
      except: ["./apps/shared-config"],
      message: "Apps importam packages/, não outros apps",
    },
  ],
}

Notas de TypeScript

• Use extensões .js em especificadores de importação quando "moduleResolution": "NodeNext".
• Regras de limite complementam exports do package.json - ambos devem concordar.

Armadilhas

• Importações relativas ignoram limites de pacotes - ../../packages/foo/src. Correção: importe apenas o nome do pacote @acme/foo.
• Zonas excessivamente amplas - Bloqueando utilitários de teste compartilhados legítimos. Correção: globs except para **/*.test.ts.
• Arquivos Barrel reexportam tudo - index.ts se torna uma brecha. Correção: restrinja barrels ou verifique a superfície da API pública com knip.
• Falsos positivos em aliases de caminho - Resolução do ESLint não configurada. Correção: import-x/resolver-typescript com projectService.
• Regras sem CI - Desenvolvedores pulam localmente. Correção: npm run lint exigido no PR.

Alternativas

FAQs

Relacionado

• Noções Básicas de Linting - configuração plana
• Nx para Backends Node - limites baseados em tags
• Monorepo Multi-Serviço - regras de app vs pacote

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.