Dependências de pares e eliminação de código não utilizado

Dependências de pares declaram pacotes que sua biblioteca exige, mas espera que o consumidor forneça. No package.json da sua biblioteca, React deve estar em peerDependencies, não em dependencies. Quando um usuário instala sua biblioteca, npm/yarn não instala React automaticamente — a aplicação do usuário já tem React, e sua biblioteca compartilha essa instância.

Se React estiver em dependencies da sua biblioteca, npm poderá instalar uma segunda cópia do React ao lado da cópia do consumidor. Duas instâncias do React na mesma aplicação interrompem todos os ganchos e geram o erro "Invalid hook call". Ao declarar React como uma dependência de par, você informa ao npm: "Preciso de React, mas use a instância que o consumidor já tem."

Algumas dependências de pares podem ser opcionais — por exemplo, uma biblioteca compatível com styled-components e CSS Modules. Marque as dependências de pares opcionais usando peerDependenciesMeta: { 'styled-components': { optional: true } }. O npm não avisará os usuários sobre dependências de pares opcionais ausentes, mas os tipos do TypeScript ainda poderão ser fornecidos quando o pacote opcional estiver instalado.

O campo sideEffects em package.json informa aos empacotadores se é seguro eliminar código não utilizado da sua biblioteca. Definir "sideEffects": false informa ao webpack, ao Rollup e a ferramentas semelhantes que importar qualquer módulo da sua biblioteca não causa efeitos colaterais — todas as exportações não utilizadas podem ser removidas com segurança do pacote do consumidor.

Importações de CSS são um efeito colateral comum — elas injetam estilos na página como consequência da importação. Se a sua biblioteca importar arquivos CSS, defina "sideEffects": ["*.css", "*.scss"] para informar aos empacotadores que os arquivos JS podem ser eliminados com segurança, mas os arquivos CSS sempre devem ser incluídos quando importados.

Para maximizar a capacidade de eliminar código não utilizado, exporte cada componente como uma exportação nomeada do seu próprio arquivo. Em index.ts, reexporte tudo: export { Button } from './Button'. Quando um consumidor importar apenas Button, o empacotador poderá eliminar todos os outros componentes. Arquivos agregadores com reexportações permitem esse padrão.

Use bundlejs.com para testar a eliminação de código não utilizado: cole sua instrução de importação, e o site informará o tamanho real do pacote. O pacote npm size-limit permite definir limites de tamanho no seu package.json e fazer a CI falhar se o tamanho da importação exceder o limite: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Estabeleça um orçamento de tamanho para as importações da sua biblioteca. Execute npx size-limit na CI para aplicá-lo. Ver o impacto do pacote crescer com o tempo indica um aumento indevido do escopo. Uma biblioteca de componentes focada deve manter as importações de componentes individuais abaixo de alguns quilobytes. Emita alertas sobre regressões antes que elas cheguem aos consumidores.

Evite styled-components e Emotion nas bibliotecas de componentes que pretende distribuir. Essas soluções de CSS em JS em tempo de execução exigem que o consumidor instale a mesma biblioteca e versão, criando conflitos entre dependências de pares. Se o consumidor usar Tailwind ou CSS simples, ainda precisará empacotar o tempo de execução de CSS em JS. Prefira CSS Modules, que são compilados para CSS simples durante a compilação.

CSS Modules funcionam bem em bibliotecas quando combinados com um empacotador que os processe. tsup e Rollup podem incorporar a saída de CSS Modules como nomes de classe com escopo. O consumidor não precisa configurar nada — os estilos já estão delimitados e incluídos no pacote JS ou em um arquivo CSS separado que é importado.

Suas próprias ferramentas de desenvolvimento (tsup, TypeScript, bibliotecas de teste e Storybook) ficam em devDependencies — elas são necessárias apenas durante o desenvolvimento e são excluídas da instalação do npm para os consumidores. React fica tanto em peerDependencies (requisito de execução) quanto em devDependencies (necessário para compilar e testar sua biblioteca localmente).

O que definir "sideEffects": false no package.json de uma biblioteca comunica aos empacotadores?

Declare React em peerDependencies (não em dependencies) para que os consumidores compartilhem a instância do React da própria aplicação. sideEffects: false permite a eliminação completa de código não utilizado da sua biblioteca. Use sideEffects: ['*.css'] para proteger as importações de CSS contra a eliminação. Exportações nomeadas de arquivos individuais maximizam a granularidade da eliminação de código não utilizado. Aplique um orçamento de tamanho com size-limit na CI. Prefira CSS Modules a CSS em JS nas bibliotecas para evitar conflitos entre dependências de pares.