Strict mode em TypeScript: o que strict: true ativa

Strict mode é a opção "strict": true do tsconfig.json. É um único interruptor para oito flags de verificação de tipos que pegam any implícito, null e undefined não verificados, atribuições inseguras de funções e campos de classe não inicializados. No TypeScript 7, strict vem ativado por padrão. Assim é um código que passa por ele:

function double(x: number) { // noImplicitAny: x needs a type
  return x * 2;
}

function findUser(id: number): { name: string } | undefined {
  return id === 1 ? { name: "Ada" } : undefined;
}

const user = findUser(2);
console.log(user?.name ?? "no user"); // strictNullChecks: user may be undefined

try {
  JSON.parse("{");
} catch (err) { // useUnknownInCatchVariables: err is unknown
  console.log(err instanceof Error ? err.name : String(err));
}

console.log(double(21));

A saída é no user, SyntaxError e 42. Remova o : number, o ?. ou a verificação com instanceof e o arquivo deixa de compilar.

Como ativar

{
    "compilerOptions": {
        "strict": true
    }
}

As flags individuais têm prioridade sobre strict, nos dois sentidos. "strict": true, "strictNullChecks": false mantém tudo, exceto a verificação de null; "strict": false, "noImplicitAny": true ativa só essa. strict também inclui automaticamente as verificações adicionadas em versões futuras, já que novas flags da família strict entram no grupo.

O strict do TypeScript não tem nada a ver com a diretiva "use strict" do JavaScript, que é um modo de execução. O TypeScript 7 sempre gera "use strict" onde é necessário, e definir alwaysStrict: false é o erro TS5108 (a opção foi removida).

O que cada flag pega

As duas que mais mudam o código são noImplicitAny e strictNullChecks. Este bloco quebra as duas de propósito:

// This does not compile: two strict errors.
function double(x) {
  return x * 2;
}

function findUser(id: number): { name: string } | undefined {
  return id === 1 ? { name: "Ada" } : undefined;
}

const user = findUser(2);
console.log(user.name, double(2));

Ele imprime index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type. e index.ts(11,13): error TS18048: 'user' is possibly 'undefined'. Sem strict, isso compila e depois quebra em tempo de execução com TypeError: Cannot read properties of undefined (reading 'name'). Com strict, a quebra vira um erro de compilação. As correções são o primeiro bloco desta página.

strictFunctionTypes: por que existe

Uma função que só trata strings não pode ser usada onde números podem chegar. A verificação abaixo está silenciada com @ts-expect-error para que você possa rodar e ver o que o erro evita:

type Handler = (value: string | number) => void;

const shout = (s: string) => console.log(s.toUpperCase());

// @ts-expect-error strictFunctionTypes rejects this assignment
const handle: Handler = shout;

try {
  handle(42); // the type allows a number, shout cannot take one
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // s.toUpperCase is not a function
}

Sem o comentário, a atribuição é o erro TS2322, Type '(s: string) => void' is not assignable to type 'Handler'., seguido de Types of parameters 's' and 'value' are incompatible. Resta uma exceção, de propósito: parâmetros de métodos declarados com a sintaxe de método (handle(value: string | number): void dentro de uma interface) ainda são verificados da forma mais frouxa, então shout poderia ser atribuída a um método assim sem erro.

strictPropertyInitialization

Todo campo de classe precisa receber um valor na declaração ou no construtor. Três formas de atender a isso:

class Account {
  owner: string;                  // assigned in the constructor
  balance = 0;                    // initializer
  history: string[] = [];         // initializer
  lastLogin?: Date;               // optional: may stay undefined
  sessionId!: string;             // "!": assigned later, you promise

  constructor(owner: string) {
    this.owner = owner;
  }
}

const a = new Account("Ada");
a.sessionId = "s-1";
console.log(a);

Saída:

Account {
  owner: 'Ada',
  balance: 0,
  history: [],
  lastLogin: undefined,
  sessionId: 's-1'
}

As propriedades lastLogin e sessionId existem com o valor undefined porque campos de classe são campos JavaScript de verdade com target ES2022. O ! remove a verificação sem acrescentar nenhuma proteção em tempo de execução, então prefira as outras formas. Essa flag depende de strictNullChecks; desativar essa também a desativa.

Ativando o strict em um projeto existente

Mudar um projeto grande para strict de uma vez pode gerar centenas de erros. Como strict é o padrão no TypeScript 7, atualizar um projeto cujo tsconfig.json nunca mencionou strict o ativa sozinho; escreva "strict": false se precisar do comportamento antigo durante a migração. Um caminho que mantém o build passando:

1. Adicione "strict": true e desative as flags com mais erros, em geral "strictNullChecks": false e "noImplicitAny": false.
2. Corrija os erros restantes, depois ative mais uma flag e repita.
3. Para noImplicitAny, a maioria das correções são anotações de parâmetros. Para strictNullChecks, adicione | undefined onde os valores podem faltar e depois trate isso com ?., ?? ou uma verificação if.
4. Onde uma correção precisa esperar, coloque // @ts-expect-error com um motivo na linha. Ao contrário de @ts-ignore, ele aponta um erro quando o problema some, então a lista diminui sozinha.

Não recorra a as any ou ! para silenciar erros em massa: cada um esconde exatamente o bug que a flag foi criada para encontrar.

Flags úteis que o strict não inclui

Elas são separadas porque rejeitam código que muitas vezes está correto. Mesmo assim, muitos projetos as ativam.

noUncheckedIndexedAccess é a que pega mais bugs reais. Com ela ativada:

const scores = [90, 85];
const d: Record<string, number> = {};

const third: number = scores[2]; // error TS2322: Type 'number | undefined' is not assignable to type 'number'.
const c: number = d["x"];        // same error

const safe = scores[2] ?? 0;     // number
for (const s of scores) {        // for...of is not affected: s is number
    console.log(s);
}

No TypeScript 7, tsc --init ativa noUncheckedIndexedAccess e exactOptionalPropertyTypes na configuração que gera, ao lado de strict.