Noções Básicas de TypeScript para React

Receita

Configure um projeto React com TypeScript, com um tsconfig.json bem configurado, entenda como os arquivos .tsx funcionam e aprenda as anotações de tipo principais que todo desenvolvedor React precisa.

Exemplo de Trabalho

// tsconfig.json (Recomendado para Next.js 15 / React 19)
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

// src/components/Greeting.tsx
type GreetingProps = {
  name: string;
  age?: number;
};
 
export function Greeting({ name, age }: GreetingProps) {
  return (
    <div>
      <h1>Olá, {name}</h1>
      {age !== undefined && <p>Idade: {age}</p>}
    </div>
  );
}

// Uso
<Greeting name="Alice" />
<Greeting name="Bob" age={30} />

Mergulho Profundo

Como Funciona

• TypeScript adiciona verificação de tipo estática sobre o JavaScript. O compilador detecta erros de tipo antes que seu código seja executado no navegador.
• Arquivos .tsx são arquivos TypeScript que suportam a sintaxe JSX. A configuração jsx: "preserve" informa ao TypeScript para deixar o JSX intocado para que o bundler (Next.js, Vite) o manipule.
• strict: true habilita uma família de verificações rigorosas (strictNullChecks, strictFunctionTypes, noImplicitAny, etc.) que detectam a maioria dos bugs.
• moduleResolution: "bundler" corresponde à forma como os bundlers modernos resolvem imports, suportando campos exports do package.json e imports sem extensão.
• Aliases de caminho como @/* permitem que você escreva import { Button } from "@/components/Button" em vez de caminhos relativos frágeis.

Variações

Configuração Vite + React:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Adicionando opções mais rigorosas incrementalmente:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true
  }
}

Notas de TypeScript

• Sempre instale os tipos do React: npm install -D @types/react @types/react-dom. Com o React 19, os tipos vêm com o react e @types/react podem não ser necessários dependendo da sua configuração.
• Use type para props e formas simples; use interface quando precisar de declaração de mesclagem ou extends.
• Prefira unknown em vez de any. Se você precisar usar any, adicione um comentário // eslint-disable e um TODO para corrigi-lo mais tarde.

Armadilhas

• Esquecer "strict": true significa que o TypeScript não sinalizará o acesso a null ou undefined, anulando grande parte de seu valor.
• Definir jsx como "react" em vez de "preserve" ou "react-jsx" força você a import React from "react" em cada arquivo.
• skipLibCheck: true é recomendado para velocidade de build, mas pode ocultar erros de tipo em seus próprios arquivos .d.ts.
• Usar any desabilita silenciosamente a verificação de tipo para tudo o que esse valor toca downstream.

Alternativas

FAQs

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

type GreetingProps = {
  name: string;
  age?: number; // opcional
};
 
function Greeting({ name, age = 25 }: GreetingProps) {
  return <p>{name} tem {age} anos</p>;
}

Relacionado

• Tipando Props
• Padrões de Modo Estrito
• Arquivos de Declaração
• Manual do TypeScript - tsconfig