zshy

library0.7.0jsnpmunverified

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.

devops

npm install zshy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZSHY

zshy

devopsjavascriptv0.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

build

✓ import { build } from 'zshy'

✗ const build = require('zshy')

While primarily a CLI tool, `zshy` exports a programmatic `build` function for advanced scripting or integration.

ZshyConfig

✓ import type { ZshyConfig } from 'zshy'

Imports the type definition for `zshy`'s configuration object, useful for type-checking when programmatically constructing config.

ZshyExports

✓ import type { ZshyExports } from 'zshy'

Imports the type definition for the exports mapping used within `package.json#/zshy`.

Demonstrates how to install `zshy` and configure a multi-entrypoint TypeScript library build using the `zshy` field in `package.json`.

npm install --save-dev zshy // package.json { "name": "my-pkg", "version": "1.0.0", "type": "module", // Important for ESM output "scripts": { "build": "zshy" }, "zshy": { "exports": { ".": "./src/index.ts", "./utils": "./src/utils.ts", "./plugins/*": "./src/plugins/*" // Wildcard for dynamic subpaths } } } // src/index.ts export const greet = (name: string) => `Hello, ${name}!`; export type GreetFn = typeof greet; // src/utils.ts export const add = (a: number, b: number) => a + b; npx zshy # This command will process your TypeScript files, generate CJS/ESM outputs, and update package.json#exports.

zshy --version

Debug

Known issues

breakingZshy has a peer dependency on TypeScript `>5.5.0`. Using an older version of TypeScript will lead to installation failures or unexpected build behavior.

fix

Ensure your project's `typescript` dependency is updated to `5.5.0` or newer (e.g., `npm install typescript@latest`).

affects: <0.7.0

gotchaZshy automatically generates and overwrites the `package.json#/exports` and `jsr.json` fields. Any manual modifications to these fields may be lost on subsequent builds.

fix

Manage your package exports exclusively through the `zshy` field in `package.json`. Avoid direct edits to `exports` or `jsr.json`.

affects: >=0.1.0

gotchaThe `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.

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.

affects: >=0.1.0

gotchaIn 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.

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.

affects: <0.4.4

gotchaZshy 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.

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.

affects: <0.3.4

Errors

Common errors & fixes

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

`zshy` requires TypeScript version `5.5.0` or higher, but an older version is installed or specified in the project.

fix

Upgrade your project's TypeScript dependency: `npm install typescript@latest` or `yarn add typescript@latest --dev`.

Error: Could not find 'package.json' or 'tsconfig.json' in the current directory or its parents.

`zshy` expects to be run from the root directory of your project, where `package.json` and `tsconfig.json` are located.

fix

Navigate to your project's root directory and rerun `npx zshy`.

Error: The "zshy" field in package.json is missing or invalid. Please refer to the documentation for correct usage.

The `zshy` configuration in your `package.json` is either entirely absent or malformed, preventing `zshy` from determining entrypoints.

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.

SyntaxError: Cannot use import statement outside a module (when running CJS output) OR require is not defined (when running ESM output)

Attempting to run a CommonJS output file in an ES Module environment (or vice-versa) without proper handling of the module type.

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`.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

typescriptrequiredRequired for core TypeScript transpilation, `zshy` leverages `tsc` internally.

Agent activity

42 hits · last 30 days

node

Resources

githubhttps://github.com/colinhacks/zshy ↗

packagehttps://www.npmjs.com/package/zshy ↗

homepagehttps://zshy.dev ↗