Configuração de Build de Produção: Vite, tsup e Rollup para Bibliotecas e Aplicações Web
Domine os fluxos modernos de empacotamento e build de produção para projetos TypeScript: entenda a separação entre checagem de tipos e transpilação ultrarrápida, configure o Vite para aplicações web corporativas e aprenda a publicar bibliotecas no npm com tsup e Rollup gerando bundles otimizados com suporte híbrido (ESM/CJS) e arquivos de definição .d.ts.
📑 Índice do Conteúdo
1. O Paradigma Moderno de Compilação: Transpilação vs Type-Checking
Historicamente, o compilador oficial tsc era responsável por duas tarefas simultâneas: validar os tipos estáticos e emitir os arquivos JavaScript transpilados. À medida que as bases de código cresceram para dezenas ou centenas de milhares de linhas, o tempo de compilação do tsc tornou-se um gargalo em loops de desenvolvimento e deploys contínuos.
A engenharia moderna de software resolveu essa questão separando as duas atribuições:
- Transpilação (Strip Types): Compiladores de altíssima performance escritos em Go ou Rust (como esbuild, SWC e oxc) removem as anotações de tipo do TypeScript em frações de milissegundo, gerando o JavaScript final para browsers e Node.js.
- Checagem Estática de Tipos (Type-Checking): O
tscoficial é executado com a flag--noEmitem background na IDE ou no pipeline de CI/CD, garantindo que nenhum erro de tipo passe despercebido.
Em projetos profissionais, o comando de build no
package.json orquestra ambas as fases sequencialmente:
"scripts": {
"type-check": "tsc --noEmit",
"build": "tsc --noEmit && vite build"
}
Dessa forma, se houver qualquer erro estático, o build é interrompido imediatamente antes de gastar recursos gerando o bundle.
2. Empacotando Aplicações Web com Vite
O Vite consolidou-se como a ferramenta de build e servidor de desenvolvimento definitiva para Single Page Applications (SPAs) modernas. Durante o desenvolvimento, o Vite serve o código como ES Modules nativos diretamente para o navegador sem criar bundles intermediários pesados, proporcionando Hot Module Replacement (HMR) quase instantâneo.
Para a produção, o Vite utiliza o poder do Rollup por baixo dos panos para criar bundles altamente otimizados com divisão de código (code-splitting), tree-shaking agressivo e hash nos nomes dos arquivos para cache seguro de navegadores:
// vite.config.ts
import { defineConfig } from 'vite';
import path from 'node:path';
export default defineConfig({
// 1. Resolução de aliases alinhada com o tsconfig.json
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'@domain': path.resolve(__dirname, './src/domain'),
'@services': path.resolve(__dirname, './src/services')
}
},
// 2. Otimizações de compilação de produção
build: {
target: 'es2022',
outDir: 'dist',
sourcemap: true,
minify: 'esbuild',
rollupOptions: {
output: {
// Separação de fornecedores em chunks isolados para otimizar cache HTTP
manualChunks(id) {
if (id.includes('node_modules')) {
return 'vendor';
}
}
}
}
}
});
3. Criando Bibliotecas e Pacotes Corporativos com `tsup`
Quando o objetivo não é uma aplicação web completa com HTML, mas sim uma biblioteca de código, SDK ou pacote corporativo para publicação no npm ou compartilhamento em monorepos, o tsup é a escolha de excelência. Criado sobre o esbuild, ele compila arquivos TypeScript em milissegundos e gera suporte híbrido (CommonJS e ES Modules) com arquivos de declaração .d.ts automáticos.
// tsup.config.ts
import { defineConfig } from 'tsup';
export default defineConfig({
// 1. Ponto de entrada da biblioteca
entry: ['src/index.ts'],
// 2. Formatos de saída: CJS para compatibilidade legada e ESM para ecossistema moderno
format: ['cjs', 'esm'],
// 3. Geração automática dos tipos estáticos .d.ts
dts: true,
// 4. Limpeza da pasta dist a cada build
clean: true,
// 5. Minificação e mapas de código
minify: true,
sourcemap: true,
// 6. Alvo da sintaxe JavaScript gerada
target: 'node18'
});
4. A Especificação Moderna de Package Exports (`package.json`)
Para que sua biblioteca TypeScript funcione perfeitamente tanto em projetos que utilizam require() (CommonJS) quanto naqueles com import (ESM), sem quebras de tipos estáticos, o campo exports no package.json deve ser configurado com rigor:
{
"name": "@webzoneware/enterprise-sdk",
"version": "1.0.0",
"type": "module",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"require": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
}
},
"files": [
"dist"
]
}
A chave
"types" deve sempre vir antes de "default" em cada condição. Se você colocar "default" primeiro, algumas ferramentas de resolução do TypeScript ignorarão o arquivo de definição de tipos e acusarão falta de tipagem.
5. Rollup Puro para Pipelines Avançados
Enquanto o Vite atende aplicações e o tsup cuida de bibliotecas convencionais, o Rollup puro continua sendo a melhor ferramenta quando você precisa de controle cirúrgico sobre a árvore de dependências (AST), empacotamento de plugins customizados, injeção de banners de licença e transformações de assets estáticos embutidos.
build-pipeline-simulacao.ts
// =====================================================================
// LAB: SIMULAÇÃO DE UM PIPELINE DE BUILD E VERIFICAÇÃO DE TIPOS
// =====================================================================
interface BuildAsset {
nomeArquivo: string;
formato: 'cjs' | 'esm' | 'dts';
tamanhoBytes: number;
conteudoResumido: string;
}
interface BuildConfig {
alvo: string;
minify: boolean;
gerarDts: boolean;
formatos: ('cjs' | 'esm')[];
}
class PipelineBuildTypeScript {
public constructor(private readonly config: BuildConfig) {}
// Simula a etapa de checagem estática de tipos (tsc --noEmit)
public verificarTipos(arquivosTs: string[]): boolean {
console.log('1. Executando checagem estática com tsc --noEmit...');
for (const arq of arquivosTs) {
console.log(` -> Validando sintaxe e tipos em: ${arq} [OK]`);
}
console.log('✅ Checagem estática concluída com 0 erros!n');
return true;
}
// Simula a etapa de transpilação e bundle
public empacotar(): BuildAsset[] {
console.log('2. Iniciando transpilação ultrarrápida de produção...');
const assets: BuildAsset[] = [];
for (const formato of this.config.formatos) {
const ext = formato === 'esm' ? '.mjs' : '.js';
assets.push({
nomeArquivo: `index${ext}`,
formato,
tamanhoBytes: formato === 'esm' ? 4120 : 4380,
conteudoResumido: `export const version = "1.0.0"; // Bundle ${formato.toUpperCase()}`
});
}
if (this.config.gerarDts) {
console.log('3. Extraindo definições de tipo .d.ts para os consumidores...');
assets.push({
nomeArquivo: 'index.d.ts',
formato: 'dts',
tamanhoBytes: 1240,
conteudoResumido: 'export declare const version: string;'
});
}
return assets;
}
}
// Simulação de Execução
function executarPipeline() {
console.log('=== PIPELINE DE BUILD ENTERPRISE (VITE / TSUP SIMULATOR) ===');
const config: BuildConfig = {
alvo: 'es2022',
minify: true,
gerarDts: true,
formatos: ['esm', 'cjs']
};
const pipeline = new PipelineBuildTypeScript(config);
// Passo 1: Type Checking
const sucesso = pipeline.verificarTipos(['src/index.ts', 'src/domain/cliente.ts', 'src/utils/math.ts']);
if (sucesso) {
// Passo 2: Bundle
const arquivosGerados = pipeline.empacotar();
console.log('nArquivos emitidos no diretório /dist:');
arquivosGerados.forEach(asset => {
console.log(` 📦 ${asset.nomeArquivo.padEnd(14)} | Formato: ${asset.formato.toUpperCase().padEnd(4)} | ${(asset.tamanhoBytes / 1024).toFixed(2)} KB`);
});
console.log('n🚀 Build de produção pronto para publicação no npm ou deploy em CDN!');
}
}
executarPipeline();
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE