{"id":14400,"library":"zshy","title":"Zshy TypeScript Library Build Tool","description":"Zshy (pronounced \"zee-shy\") is a bundler-free build tool specifically designed for TypeScript libraries, leveraging `tsc` for core transpilation. It aims to simplify the build process by requiring no separate configuration file, instead inferring settings from `package.json` and `tsconfig.json`. Key features include declarative entrypoint mapping within `package.json#/zshy`, automatic generation of `\"exports\"` and `\"jsr.json\"` fields, and native support for dual-module builds (ESM and CJS) from a single TypeScript source. It currently stands at version 0.7.0, with an active development pace indicated by frequent releases, and differentiates itself by its `tsc`-powered, no-bundler, no-config philosophy, making it an ideal choice for straightforward TypeScript library projects needing robust dual-package support without the complexity of traditional bundlers.","status":"active","version":"0.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/colinhacks/zshy","tags":["javascript","typescript","build-tool","compiler","dual-package","esm","cjs","library","tsc"],"install":[{"cmd":"npm install zshy","lang":"bash","label":"npm"},{"cmd":"yarn add zshy","lang":"bash","label":"yarn"},{"cmd":"pnpm add zshy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for core TypeScript transpilation, `zshy` leverages `tsc` internally.","package":"typescript","optional":false}],"imports":[{"note":"While primarily a CLI tool, `zshy` exports a programmatic `build` function for advanced scripting or integration.","wrong":"const build = require('zshy')","symbol":"build","correct":"import { build } from 'zshy'"},{"note":"Imports the type definition for `zshy`'s configuration object, useful for type-checking when programmatically constructing config.","symbol":"ZshyConfig","correct":"import type { ZshyConfig } from 'zshy'"},{"note":"Imports the type definition for the exports mapping used within `package.json#/zshy`.","symbol":"ZshyExports","correct":"import type { ZshyExports } from 'zshy'"}],"quickstart":{"code":"npm install --save-dev zshy\n\n// package.json\n{\n  \"name\": \"my-pkg\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\", // Important for ESM output\n  \"scripts\": {\n    \"build\": \"zshy\"\n  },\n  \"zshy\": {\n    \"exports\": {\n      \".\": \"./src/index.ts\",\n      \"./utils\": \"./src/utils.ts\",\n      \"./plugins/*\": \"./src/plugins/*\"  // Wildcard for dynamic subpaths\n    }\n  }\n}\n\n// src/index.ts\nexport const greet = (name: string) => `Hello, ${name}!`;\nexport type GreetFn = typeof greet;\n\n// src/utils.ts\nexport const add = (a: number, b: number) => a + b;\n\n\nnpx zshy\n# This command will process your TypeScript files, generate CJS/ESM outputs, and update package.json#exports.","lang":"typescript","description":"Demonstrates how to install `zshy` and configure a multi-entrypoint TypeScript library build using the `zshy` field in `package.json`."},"warnings":[{"fix":"Ensure your project's `typescript` dependency is updated to `5.5.0` or newer (e.g., `npm install typescript@latest`).","message":"Zshy has a peer dependency on TypeScript `>5.5.0`. Using an older version of TypeScript will lead to installation failures or unexpected build behavior.","severity":"breaking","affected_versions":"<0.7.0"},{"fix":"Manage your package exports exclusively through the `zshy` field in `package.json`. Avoid direct edits to `exports` or `jsr.json`.","message":"Zshy automatically generates and overwrites the `package.json#/exports` and `jsr.json` fields. Any manual modifications to these fields may be lost on subsequent builds.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Factor build times into your CI/CD pipeline and local development workflow. Consider `zshy`'s trade-off of simplicity and `tsc` correctness against raw build speed.","message":"The `zshy` README explicitly states that the tool is not blazing fast ('Just kidding, it's slow.'). While powerful, expect longer build times compared to highly optimized bundlers, especially for larger projects.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `zshy` v0.4.4 or newer to ensure correct CJS default export behavior with named types. Review your `package.json` `type` field for correct ESM/CJS indications.","message":"In versions prior to 0.4.4, there were known issues with CJS default exports when also exporting named types, potentially leading to incorrect module resolution or bundling in consuming projects.","severity":"gotcha","affected_versions":"<0.4.4"},{"fix":"Ensure your `tsconfig.json`'s `composite` setting aligns with your project's needs. If encountering issues related to project references, consult `zshy` documentation or issue tracker for specific `tsconfig` overrides.","message":"Zshy by default may set `composite: false` in `tsconfig.json` for built outputs. If you rely on `composite: true` for project references or advanced TS build features, this might require specific configuration or careful handling to avoid conflicts.","severity":"gotcha","affected_versions":"<0.3.4"}],"env_vars":null,"search_vec":"'/zshy':56 '0.7.0':85 'activ':88 'aim':29 'automat':57 'build':4,16,33,71,134 'build-tool':133 'bundler':14,104,130 'bundler-fre':13 'choic':113 'cjs':74,141 'compil':136 'complex':127 'config':107 'configur':39 'core':26 'current':81 'declar':51 'design':19 'develop':89 'differenti':96 'dual':69,122,138 'dual-modul':68 'dual-packag':121,137 'entrypoint':52 'esm':72,140 'export':60 'featur':49 'field':63 'file':40 'free':15 'frequent':93 'generat':58 'ideal':112 'includ':50 'indic':91 'infer':42 'instead':41 'javascript':131 'jsr.json':62 'key':48 'leverag':23 'librari':3,22,117,142 'make':109 'map':53 'modul':70 'nativ':65 'need':119 'no-bundl':102 'no-config':105 'pace':90 'packag':123,139 'package.json':45,55 'philosophi':108 'power':101 'process':34 'project':118 'pronounc':7 'releas':94 'requir':36 'robust':120 'separ':38 'set':43 'shi':10 'simplifi':31 'singl':77 'sourc':79 'specif':18 'stand':82 'straightforward':115 'support':66,124 'tool':5,17,135 'tradit':129 'transpil':27 'tsc':24,100,143 'tsconfig.json':47 'typescript':2,21,78,116,132 'version':84 'within':54 'without':125 'zee':9 'zee-shi':8 'zshi':1,6","created_at":"2026-04-20T01:59:30.912722+00:00","updated_at":"2026-04-20T01:59:30.912722+00:00","problems":[{"fix":"Upgrade your project's TypeScript dependency: `npm install typescript@latest` or `yarn add typescript@latest --dev`.","cause":"`zshy` requires TypeScript version `5.5.0` or higher, but an older version is installed or specified in the project.","error":"npm ERR! ERESOLVE unable to resolve dependency tree npm ERR! While resolving: your-package@1.0.0 npm ERR! Peer dependency: typescript@>5.5.0"},{"fix":"Navigate to your project's root directory and rerun `npx zshy`.","cause":"`zshy` expects to be run from the root directory of your project, where `package.json` and `tsconfig.json` are located.","error":"Error: Could not find 'package.json' or 'tsconfig.json' in the current directory or its parents."},{"fix":"Add or correct the `\"zshy\"` field in `package.json` to specify your library's entrypoints, either as a single string path or an `exports` object.","cause":"The `zshy` configuration in your `package.json` is either entirely absent or malformed, preventing `zshy` from determining entrypoints.","error":"Error: The \"zshy\" field in package.json is missing or invalid. Please refer to the documentation for correct usage."},{"fix":"Ensure your Node.js runtime environment and the `package.json#type` field correctly align with the module format you are trying to execute. For CJS, ensure `type` is not 'module' or use `.cjs` extension. For ESM, ensure `type` is 'module' or use `.mjs`.","cause":"Attempting to run a CommonJS output file in an ES Module environment (or vice-versa) without proper handling of the module type.","error":"SyntaxError: Cannot use import statement outside a module (when running CJS output) OR require is not defined (when running ESM output)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"zshy","cli_version":null,"type":"library","homepage":"https://zshy.dev","github":"https://github.com/colinhacks/zshy","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/zshy","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}