- Outil CLI permettant de builder facilement des bibliothèques TypeScript en ESM/CJS sans bundler
- Lancé comme outil de build interne de Zod, il est désormais publié comme un outil généraliste pour toutes les bibliothèques TypeScript
- En s’appuyant sur tsc (TypeScript Compiler), il prend en charge la réécriture d’extensions, le build en dual-module et la génération automatique des exports, pour proposer un build de niveau production sans bundler
- Adapté au déploiement rapide et à l’automatisation CI/CD, et fortement recommandé lorsqu’un package de type librairie (publication simultanée ESM/CJS) est requis
- L’automatisation des déclarations de type/exports/bin aide à prévenir les erreurs de maintenance et de déploiement
Caractéristiques principales
- Build dual-module : génère en une seule fois les fichiers ESM (.js) et CJS (.cjs)
- Aucun bundler ni configuration additionnelle : fonctionne sans webpack, esbuild, rollup, avec uniquement
package.json et tsconfig.json
- Gestion déclarative des entrypoints : déclarez directement entrypoint, subpath, wildcard, etc. dans
package.json#/zshy
- Génération automatique des exports : met automatiquement à jour le champ
exports de package.json après le build
- Structure de fichiers flexible : pas de contrainte de structure figée
src/out, les extensions d’import sont aussi libres
- Gestion des assets : copie automatique des fichiers non-JS
- Support de .tsx : conversion en .js/.cjs/.mjs selon la configuration
tsconfig
- Support CLI : création automatique de
package.json#/bin lorsqu’un entrypoint bin est spécifié
- Peut être plus lent : focalisé sur la vérification des types et la transformation avec tsc, avec priorité à la fiabilité/la précision plutôt qu’à la vitesse de build
Principe de fonctionnement et différenciation
- TypeScript Compiler API pour la réécriture automatique des extensions (.js/.cjs/.mjs) et des chemins d’import
- Création simultanée des fichiers ESM/CJS et des déclarations de type (.d.ts/.d.cts) pour chaque entrypoint
- Support des entrypoints bin CLI : zshy écrit automatiquement le chemin dans
package.json#/bin et prend aussi en charge le shebang si nécessaire
- Structure de fichiers libre, il suffit de définir
outDir dans tsconfig
package.json#/exports est généré et écrasé automatiquement lors du build
Fonctionnalités avancées et compatibilité
- Support wildcard/subpath : permet de déclarer des chemins comme
./plugins/*, et build automatique de tous les sous-chemins sous le dossier src
- La plupart des options de
tsconfig.json sont respectées (certaines options liées aux modules sont écrasées pour chaque build CJS/ESM)
- Le code sans extension d’import est également accepté (
from "./utils" etc.), avec correction automatique des extensions au build
- Environnement React Native/legacy compatible aussi en mode flat build (sortie au root du package, accès via
index.js sans exports)
- Support des conditions d’exports personnalisées (
sourceDialects) : permet d’ajouter des conditions supplémentaires comme source
Avantages par rapport aux outils concurrents
- Contrairement à tshy/tsup/tsdown, regroupe tous les résultats de build dans un seul
outDir, sans création de répertoires ou de stubs de package séparés
- Exploiter l’API officielle de TypeScript maximise la compatibilité avec les flux standards les plus récents de Node.js/ESM/CJS/TS
- Sans config additionnelle ni bundler, déploiement d’un package TypeScript de niveau librairie possible avec une seule commande
Aucun commentaire pour le moment.