Arquivos de Declaração

Receita

Crie e gerencie arquivos de declaração .d.ts para tipos globais, aumento de módulo, pacotes de terceiros sem tipagem e declarações ambientais personalizadas em um projeto React/Next.js.

Exemplo de Trabalho

// types/global.d.ts - Declarações de tipo globais
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 - Variáveis de ambiente tipadas
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 - Declarando módulos sem tipagem
declare module "some-untyped-library" {
  export function doSomething(input: string): Promise<string>;
  export function configure(options: { verbose: boolean }): void;
}
 
// Importações 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álise Profunda

Como Funciona

• Arquivos .d.ts são arquivos de declaração que contêm apenas informações de tipo, sem código de tempo de execução. Eles informam ao TypeScript sobre tipos que existem em tempo de execução, mas que não são expressos em código fonte TypeScript.
• Arquivos em um diretório types/ são incluídos automaticamente se o seu tsconfig.json tiver "include": ["**/*.ts", "**/*.tsx"] ou se o caminho corresponder a um padrão include.
• Declarações ambient (declare) dizem ao TypeScript "isso existe em tempo de execução, confie em mim". Use-as para variáveis globais, módulos sem tipagem e extensões de ambiente.
• Aumento de módulo estende tipos de módulo existentes usando declare module "nome-do-modulo". É assim que você adiciona campos a ProcessEnv, estende tipos do Next.js ou corrige tipos de bibliotecas de terceiros.
• O TypeScript resolve tipos nesta ordem: arquivos de origem locais, mapeamentos paths, node_modules/@types/*, e então arquivos .d.ts personalizados em diretórios correspondentes a include.

Variações

Aumentando tipos do Next.js:

// types/next-auth.d.ts - Estendendo os tipos de sessão do next-auth
import { DefaultSession } from "next-auth";
 
declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: "admin" | "editor" | "viewer";
    } & DefaultSession["user"];
  }
}

Estendendo o 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 {}; // Necessário para tornar este um módulo

Módulos CSS Tipados:

// 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;
}

Criando um tipo utilitário 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 do TypeScript

• Arquivos de declaração com declare global { } modificam o escopo global. O arquivo deve ter pelo menos um import ou export para ser tratado como um módulo; adicione export {} se necessário.
• declare module "x" aumenta um módulo. Se o módulo já tiver tipos, suas declarações serão mescladas. Se não tiver, sua declaração substituirá o any implícito.
• Não coloque código de implementação em arquivos .d.ts. Eles são apagados durante a compilação e servem apenas como dicas de tipo.
• Use typeRoots em tsconfig.json para controlar onde o TypeScript procura por arquivos de declaração: "typeRoots": ["./types", "./node_modules/@types"].

Armadilhas

• Esquecer export {} em um arquivo com declare global faz com que o arquivo seja tratado como um script (não um módulo), e suas declarações podem não se mesclar corretamente.
• Declarações de módulo ambient (declare module "x") substituem completamente os tipos do módulo, a menos que você importe do módulo primeiro. Para aumentar, adicione uma instrução de importação.
• Pacotes @types/* do DefinitelyTyped podem entrar em conflito com tipos empacotados em versões mais recentes do pacote. Verifique se a biblioteca envia seus próprios tipos antes de instalar @types/.
• skipLibCheck: true pula a verificação de tipo de todos os arquivos .d.ts, incluindo os seus. Erros em suas declarações personalizadas serão ignorados silenciosamente.
• Tipos de variáveis de ambiente (ProcessEnv) fornecem confiança em tempo de compilação, mas nenhuma garantia em tempo de execução. A variável ainda pode estar ausente em tempo de execução. Sempre valide na inicialização.

Alternativas

FAQs

// 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

• Noções Básicas de TypeScript
• Padrões de Modo Estrito
• Tipando Respostas de API
• Tipos Utilitários