Archivos de Declaración

Receta

Crea y gestiona archivos de declaración .d.ts para tipos globales, ampliación de módulos, paquetes de terceros sin tipos y declaraciones ambientales personalizadas en un proyecto React/Next.js.

Ejemplo Funcional

// types/global.d.ts - Declaraciones de tipo globales
type User = {
  id: string;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};
 
type ApiResponse<T> = {
  data: T;
  meta: {
    page: number;
    totalPages: number;
  };
};

// types/environment.d.ts - Variables de entorno tipificadas
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    DATABASE_URL: string;
    NEXT_PUBLIC_API_URL: string;
    NEXT_PUBLIC_SITE_URL: string;
    AUTH_SECRET: string;
  }
}

// types/modules.d.ts - Declaración de módulos sin tipos
declare module "some-untyped-library" {
  export function doSomething(input: string): Promise<string>;
  export function configure(options: { verbose: boolean }): void;
}
 
// Importaciones de assets
declare module "*.svg" {
  const content: React.FC<React.SVGProps<SVGSVGElement>>;
  export default content;
}
 
declare module "*.png" {
  const src: string;
  export default src;
}
 
declare module "*.css" {
  const classes: Record<string, string>;
  export default classes;
}

Análisis Profundo

Cómo Funciona

• Los archivos .d.ts son archivos de declaración que contienen solo información de tipos, sin código en runtime. Comunican a TypeScript sobre tipos que existen en runtime pero no están expresados en el código fuente de TypeScript.
• Los archivos en el directorio types/ se incluyen automáticamente si tu tsconfig.json tiene "include": ["**/*.ts", "**/*.tsx"] o si la ruta coincide con un patrón include.
• Las declaraciones ambientales (declare) dicen a TypeScript "esto existe en runtime, confía en mí". Úsalas para variables globales, módulos sin tipos y extensiones de entorno.
• La ampliación de módulos extiende tipos de módulos existentes usando declare module "module-name". Así es como añades campos a ProcessEnv, extienden tipos de Next.js o parchas tipos de librerías de terceros.
• TypeScript resuelve tipos en este orden: archivos fuente locales, mapeos paths, node_modules/@types/*, luego archivos .d.ts personalizados en directorios que coinciden con include.

Variaciones

Ampliación de tipos de Next.js:

// types/next-auth.d.ts - Extensión de tipos de sesión de next-auth
import { DefaultSession } from "next-auth";
 
declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: "admin" | "editor" | "viewer";
    } & DefaultSession["user"];
  }
}

Extensión de Window:

// types/window.d.ts
declare global {
  interface Window {
    analytics: {
      track: (event: string, properties?: Record<string, unknown>) => void;
      identify: (userId: string) => void;
    };
    __ENV__: Record<string, string>;
  }
}
 
export {}; // Requerido para hacer esto un módulo

Módulos CSS Tipificados:

// types/css-modules.d.ts
declare module "*.module.css" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.module.scss" {
  const classes: { readonly [key: string]: string };
  export default classes;
}

Creación de un tipo utilitario global:

// types/utils.d.ts
type Prettify<T> = {
  [K in keyof T]: T[K];
} & {};
 
type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
 
type Nullable<T> = T | null;

Notas de TypeScript

• Los archivos de declaración con declare global { } modifican el scope global. El archivo debe tener al menos una import o export para ser tratado como un módulo; añade export {} si es necesario.
• declare module "x" amplía un módulo. Si el módulo ya tiene tipos, tus declaraciones se fusionan. Si no, tu declaración reemplaza el any implícito.
• No pongas código de implementación en archivos .d.ts. Se borran durante la compilación y sirven solo como pistas de tipo.
• Usa typeRoots en tsconfig.json para controlar dónde busca TypeScript los archivos de declaración: "typeRoots": ["./types", "./node_modules/@types"].

Trampas

• Olvidar export {} en un archivo con declare global hace que el archivo sea un script (no un módulo), y sus declaraciones pueden no fusionarse correctamente.
• Las declaraciones de módulos ambientales (declare module "x") reemplazan completamente los tipos del módulo a menos que importes del módulo primero. Para ampliar, añade una declaración de importación.
• Los paquetes @types/* de DefinitelyTyped pueden entrar en conflicto con tipos incluidos en versiones de paquetes más nuevas. Verifica si la librería incluye sus propios tipos antes de instalar @types/.
• skipLibCheck: true omite la comprobación de tipos de todos los archivos .d.ts, incluyendo los tuyos. Los errores en tus declaraciones personalizadas se ignorarán silenciosamente.
• Los tipos de variables de entorno (ProcessEnv) proporcionan confianza en tiempo de compilación pero sin garantía en runtime. La variable podría seguir faltando en runtime. Siempre valida al inicio.

Alternativas

Preguntas Frecuentes

// types/environment.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    DATABASE_URL: string;
    NEXT_PUBLIC_API_URL: string;
  }
}

// types/modules.d.ts
declare module "some-untyped-library" {
  export function doSomething(input: string): Promise<string>;
  export function configure(options: { verbose: boolean }): void;
}

declare module "*.svg" {
  const content: React.FC<React.SVGProps<SVGSVGElement>>;
  export default content;
}
 
declare module "*.png" {
  const src: string;
  export default src;
}

// types/window.d.ts
declare global {
  interface Window {
    analytics: {
      track: (event: string) => void;
    };
  }
}
export {};

Relacionado

• Conceptos Básicos de TypeScript
• Patrones de Modo Estricto
• Tipificación de Respuestas de API
• Tipos Utilitarios