Modo Estrito e Verificações do Compilador TypeScript

Ative as opções estritas do compilador TypeScript para capturar mais bugs em tempo de compilação e complementar o ESLint com segurança em nível de tipo.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Verifica tipos sem emitir arquivos
npx tsc --noEmit
 
# Verifica tipos em modo de observação durante o desenvolvimento
npx tsc --noEmit --watch
 
# Adicionar ao package.json
# "type-check": "tsc --noEmit"

Quando usar isso: Todo projeto TypeScript deve habilitar o modo estrito. A questão não é se, mas quão rapidamente você pode ativar cada opção.

Exemplo de Trabalho

// tsconfig.json
{
  "compilerOptions": {
    // --- Modo estrito (flag guarda-chuva) ---
    "strict": true,
    // "strict" habilita todas estas:
    //   "strictNullChecks": true,
    //   "strictFunctionTypes": true,
    //   "strictBindCallApply": true,
    //   "strictPropertyInitialization": true,
    //   "noImplicitAny": true,
    //   "noImplicitThis": true,
    //   "alwaysStrict": true,
    //   "useUnknownInCatchVariables": true,
 
    // --- Verificações estritas adicionais (não incluídas em "strict") ---
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
 
    // --- Configurações de Módulo e importação ---
    "verbatimModuleSyntax": true,
    "moduleResolution": "bundler",
    "module": "esnext",
    "target": "es2017",
 
    // --- Aliases de caminho ---
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
 
    // --- Saída ---
    "noEmit": true,
    "jsx": "preserve",
    "incremental": true,
 
    // --- Interop ---
    "esModuleInterop": true,
    "allowJs": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "skipLibCheck": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

O que isso demonstra:

• Modo strict completo habilitado como base
• Verificações adicionais além de strict para segurança máxima
• verbatimModuleSyntax para imports explícitos apenas de tipo
• noUncheckedIndexedAccess para forçar verificações de nulo em acesso a arrays e objetos
• Configurações compatíveis com Next.js (noEmit, jsx: "preserve", moduleResolution: "bundler")

Mergulho Profundo

Como Funciona

• "strict": true é uma flag guarda-chuva que habilita oito verificações estritas individuais
• Flags adicionais como noUncheckedIndexedAccess não estão incluídas em strict e devem ser habilitadas separadamente
• As verificações do TypeScript rodam em tempo de compilação e capturam uma classe inteira de bugs que o ESLint não consegue (incompatibilidades de tipo, propriedades ausentes, assinaturas de função incorretas)
• tsc --noEmit executa o verificador de tipos sem produzir arquivos de saída (o Next.js cuida da compilação via SWC)

Variações

O que cada opção estrita captura:

Habilitando o modo estrito incrementalmente:

// Passo 1: Comece com strict false, mas habilite opções uma por uma
{
  "compilerOptions": {
    "strict": false,
    "strictNullChecks": true,    // Habilite primeiro - maior impacto
    "noImplicitAny": true         // Habilite em segundo
    // Adicione mais conforme corrige os erros
  }
}

# Conta os erros restantes para acompanhar o progresso
npx tsc --noEmit 2>&1 | grep "error TS" | wc -l

Regras do typescript-eslint que complementam o tsconfig:

// Estas regras do ESLint capturam padrões que o tsc não sinaliza:
{
  rules: {
    "@typescript-eslint/no-floating-promises": "error",    // Promises não tratadas
    "@typescript-eslint/no-misused-promises": "error",     // Promises em contextos errados
    "@typescript-eslint/await-thenable": "error",           // await em algo que não é Promise
    "@typescript-eslint/no-unnecessary-condition": "warn",  // Condições sempre verdadeiras
    "@typescript-eslint/prefer-nullish-coalescing": "warn", // || vs ??
    "@typescript-eslint/strict-boolean-expressions": "warn", // Verificações de truthy em não-booleans
  },
}

Nota: Estas regras requerem parserOptions.project configurado para linting ciente de tipos.

Notas do TypeScript

// verbatimModuleSyntax força imports explícitos de tipo:
import type { User } from "@/types";        // Apenas tipo - apagado em tempo de execução
import { fetchUser } from "@/lib/api";       // Valor - mantido em tempo de execução
 
// noUncheckedIndexedAccess em ação:
const items = ["a", "b", "c"];
const first = items[0]; // Tipo: string | undefined (não string)
if (first) {
  console.log(first.toUpperCase()); // Seguro - restrito para string
}
 
// Sem noUncheckedIndexedAccess:
const risky = items[0]; // Tipo: string (mentira - pode ser undefined)
risky.toUpperCase(); // Falha em tempo de execução se o array estiver vazio

Armadilhas

Coisas que vão te pegar. Cada armadilha inclui o que dá errado, por que acontece e a correção.

• strictNullChecks cria muitos erros - Habilitar isso em um projeto existente grande pode produzir centenas ou milhares de erros. Correção: Habilite incrementalmente. Use // @ts-expect-error temporariamente para código conhecido como seguro e corrija os erros arquivo por arquivo.

• noUncheckedIndexedAccess é barulhento - Cada array[i] e obj[key] se torna T | undefined, exigindo verificações de nulo mesmo quando você sabe que o valor existe. Correção: Use a asserção de não-nulo (items[0]!) com moderação onde você verificou que o valor existe, ou use .at(0) com uma verificação de nulo.

• exactOptionalPropertyTypes quebra padrões comuns - Você não pode mais escrever { name?: string } e atribuir undefined a ele explicitamente. Correção: Habilite isso apenas se sua base de código distinguir entre propriedades "ausentes" e "explicitamente indefinidas". A maioria dos projetos pula esta opção.

• Regras ESLint cientes de tipos são lentas - Regras como no-floating-promises requerem informações de tipo completas, tornando o ESLint 2 a 5 vezes mais lento. Correção: Habilite regras cientes de tipos apenas se o compromisso valer a pena. Considere executá-las apenas no CI, não no editor.

• verbatimModuleSyntax e CommonJS - Esta opção não funciona bem com módulos CommonJS. Correção: Habilite-a apenas em projetos que usam módulos ES (o que inclui todos os projetos Next.js App Router).

Alternativas

Outras maneiras de resolver o mesmo problema - e quando cada uma é a melhor escolha.

FAQs

const items = ["a", "b", "c"];
const first = items[0]; // Tipo: string | undefined (não string)
if (first) {
  console.log(first.toUpperCase()); // Seguro após a restrição
}

npx tsc --noEmit 2>&1 | grep "error TS" | wc -l

// @ts-expect-error -- conhecido como seguro, será corrigido em JIRA-123
const value = riskyFunction();

{
  rules: {
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/no-misused-promises": "error",
    "@typescript-eslint/await-thenable": "error",
    "@typescript-eslint/prefer-nullish-coalescing": "warn",
  }
}

Relacionado

• Regras Essenciais do ESLint - Regras do ESLint que complementam o TypeScript estrito
• Plugins ESLint - Configuração do plugin @typescript-eslint
• Linting em CI/CD - executando tsc --noEmit em CI
• Configuração do ESLint para Next.js - configuração base do ESLint