- Herramienta CLI para construir fácilmente librerías TypeScript a ESM/CJS sin usar un bundler
- Empezó como herramienta interna de build de Zod, y hoy se publica como herramienta genérica para cualquier librería TypeScript
- Aprovecha tsc (TypeScript Compiler) para ofrecer build de nivel de producción sin bundler, incluyendo reescritura de extensiones, build dual de módulos y generación automática de
exports
- Ideal para despliegues rápidos y automatización CI/CD, y muy recomendable cuando necesitas construir un paquete tipo librería con publicación concurrente de ESM/CJS
- La automatización de declaraciones de tipos/exports/bin ayuda a prevenir errores de mantenimiento y despliegue
Características y funciones principales
- Build dual de módulos: genera archivos ESM (.js) y CJS (.cjs) en una sola ejecución
- Sin bundler ni configuración adicional: funciona sin webpack, esbuild, rollup, etc., y solo requiere
package.json y tsconfig.json
- Gestión declarativa de entrypoints: define de forma explícita entrypoint, subpath, wildcard, etc. en
package.json#/zshy
- Generación automática de exports: actualiza automáticamente el campo
"exports" de package.json tras el build
- Estructura de archivos flexible: no impone una estructura fija de
src/out, y permite usar extensiones de importación libremente
- Manejo de assets: copia automáticamente archivos que no son JS
- Soporte de .tsx: transforma a .js/.cjs/.mjs siguiendo la configuración de
tsconfig
- Soporte CLI: cuando se define un entrypoint de bin, crea automáticamente
package.json#/bin
- Puede ser más lento: prioriza confiabilidad y precisión sobre velocidad, enfocándose en el chequeo de tipos y transformación de tsc
Principales principios de funcionamiento y diferenciadores
- TypeScript Compiler API para reescritura automática de extensiones (.js/.cjs/.mjs) y rutas de importación
- Generación simultánea de archivos ESM/CJS y declaraciones de tipos (.d.ts/.d.cts) por cada entrypoint
- Soporte de entrypoint bin para CLI: zshy escribe automáticamente la ruta en
package.json#/bin y también soporta shebang
- Estructura de archivos flexible: solo hay que definir
outDir en tsconfig
package.json#/exports se crea y sobrescribe automáticamente durante el build
Funciones avanzadas y compatibilidad
- Soporte de wildcard/subpath: permite declarar rutas como
./plugins/*, compilando automáticamente todas las subrutas internas de src
- Cumple con la mayoría de opciones de
tsconfig.json (algunas opciones relacionadas con módulos se sobreescriben por cada build CJS/ESM)
- Permite imports sin extensión (
from "./utils", etc.), corrigiendo la extensión automáticamente en el build
- También soporta entornos React Native/legacy mediante
flat build mode (la salida se genera en la raíz del paquete y se accede por index.js sin exports)
- Soporte de condiciones de exports personalizadas (
sourceDialects): permite definir condiciones adicionales como source
Ventajas frente a herramientas competidoras
- A diferencia de tshy/tsup/tsdown y similares, guarda todos los resultados de build en un único
outDir sin crear directorios o stubs de paquete por separado
- Usa la API oficial de TypeScript y maximiza la compatibilidad con el flujo estándar actual de Node.js/ESM/CJS/TS
- Posibilita publicar paquetes TypeScript de nivel librería con un solo comando, sin configuración adicional ni bundler
Aún no hay comentarios.