TypeScript
Cómo TypeScript resuelve imports según moduleResolution, package.json, exports, types y condiciones usadas por Node.js, bundlers y paquetes modernos.
moduleResolution define cómo TypeScript convierte un specifier en un archivo con tipos, intentando imitar al runtime o bundler que ejecutará el código.
import { createProduct } from "./product.js";
import { z } from "zod";TypeScript → encuentra .ts, .tsx o .d.ts
runtime/bundler → encuentra JavaScript ejecutableEl checker puede sustituir extensiones para obtener tipos mientras conserva el specifier que utilizará el runtime.
Para proyectos procesados por Vite, Next.js, esbuild u otro bundler que soporta package exports y specifiers modernos sin todas las restricciones de Node ESM.
Modelan resolución moderna de Node.js, incluyendo el formato ESM/CommonJS determinado por extensión y package.json.
nodenext sigue las capacidades actuales de Node; node16 fija una generación de reglas más estable.
Modo heredado para CommonJS antiguo. No representa correctamente exports modernos.
Ambos deben representar la herramienta real.
{
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext"
}
}En un bundler:
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
"noEmit": true
}
}import { helper } from "./helper.js";Aunque el archivo fuente sea helper.ts, el specifier describe el archivo JavaScript que existirá después de compilar.
Bundlers pueden aceptar ./helper y resolverlo, pero no extrapoles esa regla a Node ESM nativo.
{
"type": "module"
}En Node determina cómo interpretar archivos .js dentro del package scope.
.mts emite .mjs..cts emite .cjs..ts depende de type y configuración en modos Node modernos.{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./testing": {
"types": "./dist/testing.d.ts",
"import": "./dist/testing.js"
}
}
}Controla la superficie pública y condiciones por consumidor.
La resolución evalúa condiciones según reglas del host. Mantén types antes de las condiciones runtime en mapas donde las herramientas lo requieran y verifica el package generado.
{
"types": "./dist/index.d.ts"
}Declara la entrada principal de tipos en paquetes simples. exports puede definir entradas y tipos por subpath.
Permite ofrecer declarations diferentes según versión de TypeScript.
{
"typesVersions": {
">=5.0": {
"*": ["ts5/*"]
}
}
}Es una herramienta de compatibilidad de librerías; no debe usarse si una sola declaración portable basta.
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}paths informa al checker. No reescribe imports emitidos ni configura automáticamente Node o el bundler. La herramienta runtime debe conocer el mismo alias.
Permite que TypeScript trate varios directorios como una estructura virtual unificada, útil para código generado y fuente. No mueve archivos durante emisión.
{
"imports": {
"#logger": "./src/logger.js"
}
}Node y TypeScript moderno pueden resolver aliases internos definidos por el paquete.
npx tsc --traceResolutionMuestra cada paso de resolución. Es útil cuando editor, build y runtime encuentran archivos distintos.
npx tsc --explainFilesExplica por qué un archivo pertenece al programa.
Dos copias de una librería pueden producir incompatibilidad cuando existen clases con private/protected, unique symbols o tipos nominales.
Revisa lockfile, peerDependencies y paths físicos.
import styles from "./styles.module.css";El bundler conoce el recurso; TypeScript necesita una declaración compatible:
declare module "*.module.css" {
const classes: Record<string, string>;
export default classes;
}{
"name": "@example/core",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"files": ["dist"]
}.d.ts y package.json.¿Por qué un alias en paths puede compilar y fallar al ejecutar en Node?
Porque paths solo enseña al checker dónde buscar; no cambia el specifier emitido ni configura el resolvedor de Node.
Declaration files .d.ts describe JavaScript existente sin generar implementación.