TypeScript Academy · Aula

Referências de projetos TypeScript explicadas

Utilize as configurações composite e references em compilações com vários pacotes

Referências de projetos TypeScript explicadas é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 1 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.

O que são referências de projetos

As referências de projetos permitem dividir uma base de código TypeScript em vários projetos tsconfig que declaram dependências entre si, possibilitando compilações incrementais e isoladas.

// tsconfig.json (root)
{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}

Projetos compostos

Cada projeto referenciado deve ter "composite": true no tsconfig. Isso habilita o armazenamento em cache de declarações e o acompanhamento de dependências.

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist"
  }
}

Compilando com tsc --build

Execute tsc --build (ou tsc -b) a partir da raiz para compilar todos os projetos referenciados na ordem das dependências.

# Build all projects
tsc --build

# Build and watch
tsc --build --watch

# Clean build outputs
tsc --build --clean

Recompilações incrementais

Após a primeira compilação, tsc --build recompila apenas os projetos cujos arquivos de origem ou dependências foram alterados, acelerando drasticamente repositórios grandes.

# Only changed packages are rebuilt
tsc --build
# Output: 2/5 projects up to date — skipping

Consumo de arquivos de declaração

Um projeto referenciado consome suas dependências por meio dos arquivos .d.ts gerados em dist/, em vez de analisar novamente os arquivos-fonte TypeScript.

// packages/ui imports from packages/core
import { Button } from "@myapp/core"; // resolved via dist/index.d.ts

Configuração de caminhos

Configure paths no tsconfig da raiz ou use exports em package.json para que o TypeScript resolva corretamente as importações de pacotes durante o desenvolvimento.

{
  "compilerOptions": {
    "paths": {
      "@myapp/core": ["./packages/core/src/index.ts"]
    }
  }
}

Preservando a ordem de compilação

O TypeScript determina automaticamente a ordem de compilação a partir do grafo de referências. Referências circulares são detectadas e relatadas como erros.

// Circular reference error example:
// packages/core references packages/ui
// packages/ui references packages/core
// Error: Circular project reference

outDir e rootDir

Cada projeto composto deve ter outDir e rootDir configurados para controlar a organização da saída e impedir que arquivos vazem entre os limites dos pacotes.

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

Integração com ferramentas de compilação

Turborepo, Nx e Lerna integram-se às referências de projetos para armazenar compilações em cache e paralelizá-las com base no grafo de dependências.

// turbo.json — declare TypeScript build as a pipeline step
{
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }
  }
}

Monitorando vários projetos

tsc --build --watch monitora todos os projetos referenciados e os recompila incrementalmente a cada alteração, oferecendo retorno quase instantâneo em monorrepositórios.

# Terminal: tsc --build --watch
# [9:00:01 AM] Found 0 errors. Watching for file changes.

Recapitulação: referências de projetos

As referências de projetos dividem o TypeScript em unidades de compilação isoladas e armazenáveis em cache. Defina composite: true, declare references e use tsc --build para obter compilações incrementais rápidas e corretas em monorrepositórios.

Verificação rápida

Qual opção do tsconfig é necessária para que um projeto seja referenciado por outro?

O que você aprendeu

As referências de projetos do TypeScript permitem compilações rápidas e isoladas em monorrepositórios. Configure composite: true, declare dependências por meio de references e compile com tsc --build para obter compilação incremental.

Perguntas Frequentes

A aula “Referências de projetos TypeScript explicadas” é grátis?

Sim — o texto completo de “Referências de projetos TypeScript explicadas” é 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 “Referências de projetos TypeScript explicadas”?

Utilize as configurações composite e references em compilações com vários pacotes 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 1 de 4.

Quanto tempo leva a aula “Referências de projetos TypeScript explicadas”?

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

← Voltar para TypeScript Academy