Límites de Importación

Las reglas de límites de importación imponen una arquitectura en capas para que las rutas no accedan a los internos de la base de datos y las aplicaciones no importen desplegables hermanos.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

npm install -D eslint-plugin-import-x

{
  rules: {
    "import-x/no-restricted-paths": [
      "error",
      {
        zones: [
          {
            target: "./src/routes",
            from: "./src/db",
            message: "Las rutas deben llamar a los servicios, no directamente a la capa de la base de datos",
          },
        ],
      },
    ],
  },
}

Cuándo usarlo:

• Monorepos con apps/ y packages/.
• Carpetas en capas: routes → services → repositories.
• Necesitas una aplicación automatizada, no solo diagramas en el README.

Ejemplo de Funcionamiento

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: "Usa servicios desde las rutas",
            },
            {
              target: "./src/services/**",
              from: "./src/routes/**",
              message: "Los servicios no deben importar rutas",
            },
          ],
        },
      ],
      "import-x/no-extraneous-dependencies": [
        "error",
        { devDependencies: ["**/*.test.ts", "eslint.config.js"] },
      ],
    },
  },
];

// MAL: src/routes/orders.ts
import { pool } from "../db/pool.js"; // Error de ESLint
 
// BIEN: src/routes/orders.ts
import { createOrder } from "../services/orders.js";

Lo que esto demuestra:

• no-restricted-paths bloquea importaciones específicas de carpeta a carpeta.
• no-extraneous-dependencies evita que dependencias fantasma se eleven.
• Los mensajes documentan la arquitectura prevista en fallos de CI.

Inmersión Profunda

Cómo Funciona

• ESLint resuelve las rutas de importación relativas al archivo que se está linting.
• Las zonas definen target (glob del importador) y from (glob de la fuente prohibida).
• Los monorepos añaden zonas que impiden que apps/a importe apps/b.
• Nx utiliza @nx/enforce-module-boundaries con etiquetas para una aplicación similar.

Ejemplo de Zona de Monorepo

{
  zones: [
    {
      target: "./apps/**",
      from: "./apps/**",
      except: ["./apps/shared-config"],
      message: "Las aplicaciones importan packages/, no otras aplicaciones",
    },
  ],
}

Notas de TypeScript

• Usa extensiones .js en los especificadores de importación cuando "moduleResolution": "NodeNext".
• Las reglas de límites complementan los exports de package.json - ambos deben estar de acuerdo.

Errores comunes

• Las importaciones relativas eluden los límites del paquete - ../../packages/foo/src. Solución: importa solo el nombre del paquete @acme/foo.
• Zonas demasiado amplias - Bloqueando utilidades de prueba compartidas legítimas. Solución: globs except para **/*.test.ts.
• Los archivos barril reexportan todo - index.ts se convierte en una laguna. Solución: restringe los barriles o lint la superficie de la API pública con knip.
• Falsos positivos en alias de ruta - El resolvedor de ESLint no está configurado. Solución: import-x/resolver-typescript con projectService.
• Reglas sin CI - Los desarrolladores se saltan localmente. Solución: npm run lint requerido en PR.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de Linting - configuración plana
• Nx para Backends de Node - límites basados en etiquetas
• Monorepo de Múltiples Servicios - reglas de aplicación vs paquete

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.