Módulos y Declaration Files

TypeScript extiende el sistema de módulos de JavaScript con características extra. "import type { Foo }" importa solo el tipo, no genera código JavaScript en el bundle (muy útil para tree-shaking y evitar dependencias circulares en runtime). Los path aliases definidos en tsconfig permiten usar @/components/Button en lugar de ../../../../components/Button, haciendo el código más limpio y resistente a cambios de estructura de carpetas.

Los declaration files (.d.ts) son archivos que solo contienen tipos, sin código JavaScript. Proveen información de tipos para librerías JavaScript puras que no tienen TypeScript. La comunidad mantiene DefinitelyTyped, un repositorio con tipos para miles de librerías populares, instalables con npm install @types/nombre. Las librerías modernas ya incluyen sus propios tipos (React, Prisma, Zod), así que solo necesitas @types/ para las más antiguas.

// Módulos ES en TypeScript
export interface Config { puerto: number; debug: boolean; }
export type { Config }; // Solo exportar tipo (no genera JS)

// Importar tipos (solo en compilación)
import type { Config } from "./config";
import { type Usuario, crearUsuario } from "./usuarios";

// Re-exports
export { SQL_COURSE } from "./courses/sql";
export * from "./utils";
export * as MathUtils from "./math";

// Path aliases con tsconfig
// "paths": { "@/*": ["./src/*"] }
import { Button } from "@/components/Button";
import { useAuth } from "@/hooks/useAuth";

// Declaration file (.d.ts) — agregar tipos a JS puro
// archivo: mi-libreria.d.ts
declare module "mi-libreria-sin-tipos" {
  export function formatear(valor: string): string;
  export interface Opciones { locale: string; }
  export const version: string;
}

// Augmentation — extender tipos existentes
declare global {
  interface Window {
    analytics: { track: (event: string) => void };
  }
}

// Extender tipos de Express
declare namespace Express {
  interface Request {
    usuario?: { id: string; rol: string };
  }
}

// Instalar tipos: npm install @types/node @types/express
// La mayoría ya incluye sus propios tipos: zod, prisma, react, etc.