Anotações de tipos JSDoc como ponte
Adicione tipos a arquivos JS com JSDoc antes da conversão
Anotações de tipos JSDoc como ponte é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.
JSDoc como ponte para TypeScript
TypeScript pode ler anotações de tipos JSDoc em arquivos JavaScript quando checkJs: true está habilitado. Isso permite adicionar tipos ao JS sem renomear os arquivos.
/** @type {string} */
let name = "Alice"; // TypeScript checks this as string@param e @returns
Anote os parâmetros das funções e os tipos de retorno usando tags JSDoc.
/**
* @param {string} name
* @param {number} age
* @returns {string}
*/
function greet(name, age) {
return `${name} is ${age}`;
}@typedef para tipos de objetos
Use @typedef para definir aliases de tipos reutilizáveis em JSDoc.
/**
* @typedef {Object} User
* @property {string} id
* @property {string} name
* @property {boolean} isActive
*/
/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };@template para genéricos
Use @template para escrever funções genéricas em JSDoc.
/**
* @template T
* @param {T[]} arr
* @returns {T | undefined}
*/
function first(arr) {
return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefinedImportando tipos de arquivos .ts
JSDoc oferece suporte a @type {import("./types").User} para importar tipos de TypeScript para arquivos JS.
/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };@ts-check para verificação por arquivo
Adicione // @ts-check no início de um arquivo JS para habilitar a verificação de TypeScript apenas nesse arquivo, sem ativar checkJs: true globalmente.
// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number@ts-ignore e @ts-expect-error
Suprima erros específicos de tipos JSDoc com diretivas embutidas, sem desabilitar o arquivo inteiro.
// @ts-ignore
const x = badFunction(); // single error suppressed
// @ts-expect-error
const y = anotherBad(); // error expected hereEnumerações JSDoc
Simule enumerações de TypeScript em JSDoc usando @enum.
/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };Asserções de tipos em JSDoc
Use /** @type {SomeType} */ (expression) para asserções de tipos JSDoc, equivalente a as SomeType do TypeScript.
const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typedQuando passar para .ts
As anotações JSDoc são uma ponte, não um destino. Quando um arquivo estiver totalmente anotado e estável, renomeie-o para .ts e remova os comentários de tipos JSDoc em favor da sintaxe nativa de TypeScript.
// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)Recapitulação: JSDoc como ponte
As anotações de tipos JSDoc habilitam a verificação de TypeScript em arquivos JS sem renomeá-los. Use @type, @param, @typedef e @template para adicionar segurança de tipos gradualmente antes de converter para TypeScript nativo.
Verificação rápida
Qual tag JSDoc habilita a verificação de TypeScript em um único arquivo sem o checkJs global?
O que você aprendeu
As anotações de tipos JSDoc fazem a ponte entre JavaScript e TypeScript: use @type, @param, @typedef e @template para adicionar tipos aos arquivos JS. Habilite a verificação por arquivo com // @ts-check e depois converta para TypeScript nativo quando estiver pronto.
Perguntas Frequentes
A aula “Anotações de tipos JSDoc como ponte” é grátis?
Sim — o texto completo de “Anotações de tipos JSDoc como ponte” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.
O que vou aprender em “Anotações de tipos JSDoc como ponte”?
Adicione tipos a arquivos JS com JSDoc antes da conversão Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar TypeScript Academy?
Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Anotações de tipos JSDoc como ponte”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de TypeScript Academy?
Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Iniciando a migração: allowJs e checkJs
- Anotações de tipos JSDoc como ponte
- Estratégia de conversão arquivo por arquivo
- Lidando com bibliotecas de terceiros sem tipos