- CLI para build de bibliotecas TypeScript em ESM/CJS sem bundler de forma simples
- Começou como a ferramenta interna de build da Zod e agora é disponibilizada como uma ferramenta geral para bibliotecas TypeScript
- Utilizando o tsc (TypeScript compiler), oferece suporte a build de nível de produção sem bundler, incluindo rewrite de extensão, build de módulos duais e geração automática de exports
- Adequado para implantação rápida e automação de CI/CD, com recomendação forte para construir pacotes do tipo biblioteca com publicação simultânea de ESM/CJS
- A automação de tipos/exports/bin ajuda a prevenir erros de manutenção e implantação
Recursos e principais recursos
- Build de módulos duais: gera arquivos ESM(.js) e CJS(.cjs) de uma vez
- Sem bundler/configuração adicional: funciona sem webpack, esbuild, rollup etc., exigindo apenas
package.json e tsconfig.json
- Gerenciamento declarativo de entrypoints: especifica entrypoint, subpath, wildcard etc. diretamente em
package.json#/zshy
- Geração automática de exports: atualiza automaticamente o campo
"exports" no package.json após o build
- Estrutura de arquivos livre: não impõe estrutura fixa de src/out; também permite o uso livre de extensão de import
- Gerenciamento de assets: copia automaticamente arquivos que não são JS
- Suporte a .tsx: converte para .js/.cjs/.mjs de acordo com o
tsconfig
- Suporte a CLI: gera automaticamente
package.json#/bin quando um entrypoint de bin é definido
- Pode ser mais lento: foca em verificação e transformação de tipos do tsc, priorizando confiabilidade/precisão em vez de velocidade de build
Princípios de funcionamento e diferenciais
- TypeScript Compiler API para reescrita automática de extensão (.js/.cjs/.mjs) e caminhos de import
- Gera arquivos ESM/CJS e declarações de tipos (.d.ts/.d.cts) simultaneamente para cada entrypoint
- Suporte a entrypoint bin para CLI: zshy preenche automaticamente o caminho em package.json#/bin, com suporte a shebang quando necessário
- Estrutura de arquivos livre, basta definir
outDir no tsconfig
package.json#/exports é gerado e sobrescrito automaticamente durante o build
Recursos avançados e compatibilidade
- Suporte a wildcard/subpath: permite declarações de caminho como
./plugins/* e faz build automático de todos os subcaminhos no diretório src real
- A maioria das opções de tsconfig.json é respeitada (algumas opções relacionadas a módulo são sobrescritas em CJS/ESM para cada build)
- Código com import sem extensão também é aceito (
from "./utils" etc.), com correção automática de extensão no build
- Ambiente React Native/legacy também pode ser suportado com flat build mode (saída de build na raiz do pacote, acesso via index.js sem exports)
- Suporte a
sourceDialects: suporta conditions de exports personalizadas e opções extras como condição source
Vantagens em comparação com ferramentas concorrentes
- Diferente de ferramentas como tshy/tsup/tsdown, organiza todos os resultados em um único outDir sem criar diretórios ou stubs de pacote separados
- Utiliza a API oficial do TypeScript, maximizando compatibilidade com os fluxos mais recentes de Node.js/ESM/CJS/TS
- Possível fazer distribuição de pacotes TypeScript de nível de biblioteca com um único comando, sem precisar de configs extras nem bundlers
Ainda não há comentários.