Estratégia para um pacote de tipos compartilhados
Crie um pacote de tipos dedicado, utilizado em todo o monorepo
Estratégia para um pacote de tipos compartilhados é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 3 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.
Por que usar um pacote de tipos compartilhados
Compartilhar tipos entre o front-end e o back-end elimina divergências entre contratos da API. Uma única fonte de verdade significa erros em tempo de compilação quando o formato da API muda.
// packages/types/src/index.ts
export interface User { id: string; name: string; email: string; }
export interface ApiResponse<T> { data: T; error?: string; }Estrutura do pacote
Mantenha o pacote de tipos mínimo: apenas exportações de tipos, sem lógica em tempo de execução. Assim, ele não produz efeitos colaterais e permite a eliminação de código não utilizado.
packages/types/
├── src/
│ ├── index.ts # re-exports all
│ ├── user.ts
│ ├── product.ts
│ └── api.ts
├── tsconfig.json
└── package.jsontsconfig para um pacote de tipos
Habilite emitDeclarationOnly para que nenhum JavaScript seja emitido — apenas arquivos .d.ts referenciados pelos consumidores.
{
"compilerOptions": {
"composite": true,
"declaration": true,
"emitDeclarationOnly": true,
"outDir": "./dist",
"rootDir": "./src"
}
}Consumindo o pacote de tipos
Referencie o pacote de tipos tanto na API quanto na aplicação web e importe tipos com import type para evitar sobrecarga em tempo de execução.
import type { User, ApiResponse } from "@myapp/types";
async function getUser(id: string): Promise<ApiResponse<User>> {
// ...
}Mantendo os tipos seguros para serialização
Os tipos compartilhados entre cliente e servidor devem incluir apenas valores serializáveis em JSON. Evite objetos Date — use string (ISO) no lugar.
// Good: serialization-safe
interface Event { id: string; createdAt: string; /* ISO date */ }
// Bad: Date is not JSON-serializable
interface Event { id: string; createdAt: Date; }Versionando o pacote de tipos
Versione seu pacote de tipos usando versionamento semântico. Uma alteração incompatível (remover ou renomear um campo) aumenta a versão principal.
# Breaking change: major bump
npm version major
# Adding optional fields: minor bump
npm version minorGerando tipos a partir do OpenAPI
Automatize o pacote de tipos gerando-o a partir de uma especificação OpenAPI usando openapi-typescript. Isso garante que os tipos sempre correspondam ao back-end.
npx openapi-typescript ./api/openapi.yaml -o ./packages/types/src/api.tsUsando Zod para tipos em tempo de execução e de compilação
Defina tipos com esquemas Zod e infira tipos TypeScript a partir deles. Tanto a validação em tempo de execução quanto os tipos estáticos vêm da mesma fonte.
import { z } from "zod";
export const UserSchema = z.object({ id: z.string(), name: z.string() });
export type User = z.infer<typeof UserSchema>;Evitando dependências circulares
O pacote de tipos não deve importar de outros pacotes do espaço de trabalho para evitar cadeias de dependências circulares. Mantenha-o como um nó folha no grafo de dependências.
// types/ should not import from ui/ or api/
// ui/ and api/ both import from types/Testando a correção dos tipos
Use tsd para escrever afirmações em nível de tipo que verifiquem se os tipos compartilhados correspondem às expectativas.
import { expectType } from "tsd";
import type { User } from "@myapp/types";
expectType<User>({ id: "1", name: "Alice", email: "a@b.com" });Recapitulação: estratégia de tipos compartilhados
Um pacote de tipos compartilhados elimina divergências da API: emita apenas declarações, mantenha os tipos serializáveis em JSON, use versionamento semântico, gere-os opcionalmente a partir do OpenAPI e teste com tsd.
Verificação rápida
Por que os tipos compartilhados da API devem usar string em vez de Date?
O que você aprendeu
Um pacote de tipos compartilhados é uma única fonte de verdade para contratos da API. Mantenha-o apenas com declarações, seguro para JSON, versionado com versionamento semântico e, opcionalmente, gerado a partir do OpenAPI para eliminar divergências entre front-end e back-end.
Aprenda TypeScript com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 101
- Aulas
- 352
Perguntas Frequentes
A aula “Estratégia para um pacote de tipos compartilhados” é grátis?
Sim — o texto completo de “Estratégia para um pacote de tipos compartilhados” é 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 “Estratégia para um pacote de tipos compartilhados”?
Crie um pacote de tipos dedicado, utilizado em todo o monorepo 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 3 de 4.
Quanto tempo leva a aula “Estratégia para um pacote de tipos compartilhados”?
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
- Referências de projetos TypeScript explicadas
- Workspaces pnpm com TypeScript
- Estratégia para um pacote de tipos compartilhados
- Compilações incrementais e cache em monorepos