Módulos en TypeScript: import/export, resolución y paths en tsconfig

TypeScript usa el sistema de módulos de JavaScript (ES modules) con algunas extensiones específicas para tipos. Entender cómo se importan y exportan valores y tipos, cómo funciona la resolución de módulos y cómo configurar los paths en tsconfig es imprescindible para cualquier proyecto más allá del tutorial inicial.

import y export de valores y tipos

La sintaxis de import/export de ES modules funciona igual en TypeScript. Lo único añadido es la posibilidad de exportar e importar tipos:

// usuario.ts
export interface Usuario {
  id: number;
  nombre: string;
}

export function crearUsuario(nombre: string): Usuario {
  return { id: Date.now(), nombre };
}

export const URL_API = "https://api.ejemplo.com";

// main.ts
import { Usuario, crearUsuario, URL_API } from "./usuario";
import type { Usuario } from "./usuario"; // solo importa el tipo

import type: evitar side effects y mejorar el tree-shaking

import type garantiza que la importación es únicamente un tipo y será eliminada completamente en la compilación. Esto evita ejecutar el código del módulo si solo necesitas el tipo, y es obligatorio cuando usas isolatedModules: true para importar tipos que se re-exportan:

// Con import type, el módulo usuario.ts no se ejecuta si no usas sus valores
import type { Usuario } from "./usuario";

function procesar(u: Usuario): string {
  return u.nombre;
}

Re-exportar: el patrón barrel

Un fichero index.ts que re-exporta todo el contenido de un módulo simplifica las importaciones en el resto del proyecto:

// src/modelos/index.ts
export type { Usuario } from "./usuario";
export type { Producto } from "./producto";
export { crearUsuario } from "./usuario";

// Ahora en lugar de importar desde rutas específicas:
import { Usuario, Producto, crearUsuario } from "../modelos";

Resolución de módulos: node vs bundler

La opción moduleResolution en tsconfig controla cómo TypeScript busca los ficheros. Los valores más relevantes en 2026 son:

• node: resolución clásica de Node.js, sin soporte para las condiciones exports del package.json moderno.
• node16 / nodenext: resolución para Node.js 16+ con soporte de ESM y condiciones de exports. Requiere extensiones explícitas en las importaciones (.js, no .ts).
• bundler: resolución pensada para usar con Vite, esbuild, Webpack y similares. Soporta exports del package.json y no requiere extensión en los imports.

// tsconfig.json para proyectos con bundler (Vite, Next.js)
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Aliases de paths en tsconfig

Los path aliases evitan las rutas relativas largas (../../../componentes/Boton) y permiten importaciones más limpias:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@componentes/*": ["src/componentes/*"],
      "@hooks/*":       ["src/hooks/*"],
      "@utils/*":       ["src/utils/*"],
      "@tipos/*":       ["src/tipos/*"]
    }
  }
}

// Ahora puedes importar así:
import { Boton } from "@componentes/Boton";
import { useAuth } from "@hooks/useAuth";

Nota: los path aliases de tsconfig solo afectan al type-checking. Si usas un bundler, necesitas configurar los mismos aliases en Vite, Webpack o el tool correspondiente para que la resolución en tiempo de ejecución también funcione.

ESM vs CommonJS en proyectos reales

En proyectos Node.js la elección entre ESM y CommonJS afecta a la configuración del tsconfig y del package.json. ESM requiere "type": "module" en package.json y extensiones .mjs o .js en los imports. CommonJS es el default histórico pero está siendo desplazado. Para librerías npm, publicar los dos formatos sigue siendo la opción más compatible, usando un campo exports en package.json que apunte a cada versión.

Imagen: Pexels / Godfrey Atima