Empacotamento com Rollup e tsup para bibliotecas

A configuração padrão do Vite é otimizada para aplicações: empacota tudo, gerencia recursos e gera um index.html. Para uma biblioteca de componentes, você precisa de uma saída diferente: arquivos JavaScript puros em ESM/CJS, sem sobrecarga de execução, sem React empacotado e com declarações TypeScript adequadas. O modo de biblioteca do Vite funciona, mas Rollup e tsup são mais apropriados para essa finalidade.

O Rollup é há anos o empacotador padrão para bibliotecas JavaScript. Ele produz uma saída limpa e eficiente, com excelente eliminação de código não utilizado, e oferece suporte aos formatos de saída ESM e CJS. A elevação de escopo do Rollup elimina a sobrecarga dos invólucros de módulos, produzindo os menores pacotes de biblioteca possíveis.

tsup é um empacotador de TypeScript sem configuração, baseado no esbuild. Ele é muito mais rápido que o Rollup (o esbuild compila em microssegundos, em vez de milissegundos). A configuração mínima: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } produz automaticamente os dois formatos de módulo e as declarações de TypeScript.

As opções principais do tsup: entrada é a matriz de arquivos que servem como pontos de entrada. formato especifica os formatos de saída: ['esm', 'cjs']. declarações: verdadeiro gera arquivos de declaração de TypeScript .d.ts junto com a saída JS. alvo define o ambiente mínimo do JavaScript (esnext ou es2020). divisão: falsa mantém a saída em arquivos únicos.

esbuild (via tsup) compila de 10 a 100 vezes mais rápido que Rollup. Rollup gera uma saída ligeiramente mais otimizada, com melhor granularidade na eliminação de código não utilizado e mais controle sobre os limites dos blocos. Para a maioria das bibliotecas de componentes, a velocidade do tsup é vantajosa durante o desenvolvimento. Para obter o máximo controle sobre a eliminação de código não utilizado ou lidar com configurações complexas com várias entradas, prefere-se Rollup.

A configuração mais importante do empacotador para uma biblioteca React é: nunca empacote React ou ReactDOM. Marque-os como externos para excluí-los da sua saída. Se a sua biblioteca empacotar React, os consumidores acabarão com duas cópias do React — uma do seu pacote e outra da aplicação deles. Isso interrompe todos os ganchos do React devido à existência de várias instâncias do React.

Na configuração do tsup, use a opção external: external: ['react', 'react-dom']. Na configuração do Rollup, defina external: ['react', 'react-dom', 'react/jsx-runtime']. Inclua react/jsx-runtime se a sua biblioteca usar a transformação JSX. Marque também como externas quaisquer outras dependências de pares declaradas pela sua biblioteca.

Uma configuração mínima do Rollup para uma biblioteca TypeScript requer três plug-ins: @rollup/plugin-typescript para compilar TypeScript, @rollup/plugin-node-resolve para resolver importações de node_modules e @rollup/plugin-commonjs para converter dependências CommonJS em ESM para o pacote. Adicione rollup-plugin-dts para os arquivos de declaração.

Uma saída típica de uma biblioteca em dois formatos inclui: dist/esm/index.js e dist/esm/index.d.ts para consumidores de ESM, e dist/cjs/index.js e dist/cjs/index.cjs para consumidores de CJS. O campo de exportações de package.json mapeia esses caminhos para os ambientes corretos. Os arquivos de declaração do TypeScript ficam ao lado de seus equivalentes em JS.

Bibliotecas grandes se beneficiam de vários pontos de entrada, para que os consumidores importem apenas o que precisam. Por exemplo: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Cada entrada recebe seus próprios arquivos de saída. O campo de exportações de package.json mapeia cada caminho público para sua saída: './utils' → './dist/utils.js'.

Adicione o comando de compilação aos scripts de package.json: "build": "tsup". O tsup lê sua configuração de tsup.config.ts na raiz. O script de publicação prévia deve executar a compilação: "prepublishOnly": "npm run build" garante que seu pacote seja sempre compilado antes da publicação no npm.

tsup (alimentado por esbuild) oferece empacotamento rápido sem configuração, com formato: ['esm', 'cjs'] e declarações: true. Rollup oferece um controle mais granular da eliminação de código não utilizado com @rollup/plugin-typescript. A regra fundamental é: sempre marque react, react-dom e todas as dependências de pares como externas para evitar empacotá-las. Gere a saída em dist/esm/ e dist/cjs/, com declarações TypeScript correspondentes. Vários pontos de entrada permitem uma eliminação de código não utilizado mais granular para os consumidores.