TypeScript
Organización de código con módulos ES y uso de import type y export type para separar dependencias de tipos del JavaScript emitido.
TypeScript distingue nombres usados como valores runtime de nombres usados únicamente como tipos. Los módulos deben expresar esa diferencia para que la emisión coincida con el runtime.
import type { Product } from "./product.js";
import { createProduct } from "./product.js";interface Product {
id: string;
}
class ProductModel {}Product existe solo como tipo.ProductModel existe como valor constructor y como tipo de instancia.import { ProductModel } from "./product.js";Puede necesitar conservarse en JavaScript porque el valor existe en runtime.
import type { Product } from "./product.js";Se elimina completamente de la salida. Por eso no puede utilizarse como valor:
new Product();import {
createProduct,
type Product,
type ProductId,
} from "./product.js";Permite agrupar una sola declaración de import manteniendo la intención por símbolo.
export type {
Product,
ProductId,
} from "./product.js";No crea una exportación runtime.
export { createProduct } from "./product.js";Sí participa en el grafo runtime.
Con esta opción, TypeScript adopta una regla directa:
type se eliminan.Esto evita que el compilador adivine si debe eliminar un import de valor.
{
"compilerOptions": {
"verbatimModuleSyntax": true
}
}También hace visibles incompatibilidades entre la sintaxis elegida y el módulo de salida, en lugar de reescribir silenciosamente ESM a CommonJS en ciertos escenarios.
Sin import type, una herramienta que transpila archivo por archivo puede no conocer el uso global y conservar o eliminar imports de forma diferente.
import { Product } from "./product.js";
function render(product: Product) {}Escribe la intención:
import type { Product } from "./product.js";Herramientas como Babel, SWC o esbuild transforman un archivo sin el programa completo. isolatedModules detecta construcciones que no pueden transpilarse correctamente bajo ese modelo.
No cambia la emisión por sí solo; activa diagnósticos de compatibilidad.
Para generar declarations en paralelo o por archivo, isolatedDeclarations exige que exports tengan información suficiente sin inferencia global compleja.
export function calculateTotal(
subtotal: number,
tax: number,
): number {
return subtotal + tax;
}Los tipos públicos explícitos facilitan generación de .d.ts independiente.
Controla cuándo un archivo se trata como módulo. En proyectos modernos puede detectar imports, exports, JSX o configuración del entorno.
{
"compilerOptions": {
"moduleDetection": "force"
}
}force evita que archivos sin import/export contaminen el global accidentalmente.
import type { Plugin } from "./plugin.js";No evalúa plugin.js en runtime.
Si el módulo necesita registrar un side effect, debes importarlo como valor/efecto:
import "./register-plugin.js";type ModuleShape = typeof import("./product.js");Obtiene el tipo del namespace del módulo sin crear por sí solo un import runtime.
type Product = import("./product.js").Product;Es útil en declaration files o JSDoc, aunque import type suele ser más legible en código normal.
const module = await import("./editor.js");Esto sí es una expresión runtime que retorna Promise. No debe confundirse con import type ni con el tipo import("...").
export { createProduct } from "./create-product.js";
export type {
Product,
ProductId,
CreateProductInput,
} from "./product.types.js";La API pública distingue claramente valores y tipos.
¿Por qué un token de inyección basado en una clase no debería importarse con import type?
Porque el contenedor necesita el constructor como valor durante ejecución. import type elimina completamente ese import.
Resolución de módulos y package exports explica cómo el checker encuentra archivos que el runtime también podrá cargar.