zshy 0.0.5 → 0.0.7

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
 
-  <h1 align="center">⚜️<br/><code>zshy</code></h1>
-  <p align="center">Gold-standard build tool for TypeScript libraries.
+  <h1 align="center">🐒<br/><code>zshy</code></h1>
+  <p align="center">The no-bundler build tool for TypeScript libraries. Powered by <code>tsc</code>.
     <br/>
     by <a href="https://x.com/colinhacks">@colinhacks</a>
   </p>
@@ -15,42 +15,83 @@
 <a href="https://github.com/colinhacks/zshy" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zshy" alt="stars"></a>
 </p>
 
-<div align="center">
+<!-- <div align="center">
   <a href="https://github.com/colinhacks/zshy">GitHub</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://twitter.com/colinhacks">𝕏</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://bsky.app/profile/colinhacks.com">Bluesky</a>
   <br />
-</div>
+</div> -->
 
 <br/>
 <br/>
 <br/>
 
-
 <!-- ## What is `zshy`? -->
 
 <h2 align="center">What is <code>zshy</code>?</h2>
 
 `zshy` is a simple, zero-config build tool for transpiling TypeScript libraries. It was originally created as internal build tool for [Zod](https://github.com/colinhacks/zod) but is now available as a general-purpose tool for TypeScript libraries.
 
+<br/>
+
 ### Features
 
 - 🧱 **Dual-module builds** — Builds ESM and CJS outputs from a single TypeScript source file
 - 👑 **Powered by `tsc`** — No bundling, no extra configs, just good old-fashioned `tsc`
-- 📝 **Declarative config** — No build scripts, just a simple `"zshy"` field in your `package.json`
+- 🟦 **No config file** — Reads only from your `package.json` and `tsconfig.json` (configurable)
+- 📝 **Declarative entrypoint map** — Specify your TypeScript entrypoints in `package.json#/zshy`
 - 🤖 **Auto-generated `"exports"`** — Writes `"exports"` map directly into your `package.json`
-- 🟦 **Respects your `tsconfig.json`**
-- 📂 **Unopinionated about file structure** — Use any file structure you like
-- 🔗 **Unopinionated about import extensions** — Use any import syntax TypeScript supports: extensionless, `.js`, `.ts`
-- ⚛️ **Supports `.tsx`**
-- 📱 **Supports React Native** 
-- 🐌 **Blazing fast** — Just kidding, it's slow. But `tsc` is about to get 10x faster!
+- 🐚 **CLI-friendly** — First-class `"bin"` support
+- 📂 **Supports any file structure** — Use any file structure you like
+- 🔗 **Supports extensionless imports** — Use any import syntax TypeScript supports: extensionless, `.js`, `.ts`
+- ⚛️ **Supports `.tsx`** — Rewrites to `.js/.cjs/.mjs` per your `tsconfig.json#/jsx*` settings
+- 📱 **Supports React Native** — Supports a [flat build mode](#can-it-support-react-native-legacy-or-non-nodejs-environments) designed for bundlers that don't support `package.json#/exports`
+- 🐌 **Blazing fast** — Just kidding, it's slow. But [it's worth it](#is-it-fast).
 
 <br/>
+
 <br/>
-<h2 align="center">Usage</h2>
+<br/>
+
+<h2 align="center">How does it work?</h2>
+
+Each `.ts` file is transpiled to `.js/.d.ts` (ESM) and `.cjs/.d.cts` (CommonJS).
+
+```bash
+$ tree .
+├── package.json # if type == "module"
+├── src
+│   └── index.ts
+└── dist # generated
+  ├── index.js
+  ├── index.cjs
+  ├── index.d.ts
+  └── index.d.cts
+```
+
+All relative `import`/`export` statements are rewritten to the appropriate extension during the build:
+
+| Original path      | Result (ESM)       | Result (CJS)        |
+| ------------------ | ------------------ | ------------------- |
+| `from "./util"`    | `from "./util.js"` | `from "./util.cjs"` |
+| `from "./util.ts"` | `from "./util.js"` | `from "./util.cjs"` |
+| `from "./util.js"` | `from "./util.js"` | `from "./util.cjs"` |
+
+Existing build tools (tsup, tsdown, etc) perform a similar transform during their bundling step. Unfortunately vanilla `tsc` [does not support extension rewriting](https://github.com/microsoft/TypeScript/issues/16577#issuecomment-754941937), leaving library authors with no choice but to use a bundler...
+
+...until now. `zshy` implements extension rewriting during the `tsc` build step via the official [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) — specifically, the `ts.TransformerFactory` API for defining AST-level code transforms. This obviates the need for a bundler. The result is a tool that I consider to be the "holy grail" of TypeScript library build tools:
+
+- performs dual-module (ESM + CJS) builds
+- type checks your code
+- leverages `tsc` for gold-standard transpilation
+- doesn't require a bundler
+- doesn't require another config file (just `package.json` and `tsconfig.json`)
+
+<br/>
+<br/>
+<h2 align="center">Quickstart</h2>
 
 <br/>
 
@@ -72,11 +113,85 @@ Specify your package entrypoint with the `"zshy"` key in `package.json`.
 {
   "name": "my-pkg",
   "version": "1.0.0",
-  "zshy": "./src/index.ts" // package entrypoint
+  "zshy": "./src/index.ts" // 👈 package entrypoint
+}
+```
+
+<br/>
+
+### 3. Run a build
+
+```bash
+$ npx zshy
+
+→  Starting zshy build 🐒
+→  Detected project root: /Users/colinmcd94/Documents/projects/zshy
+→  Reading package.json from ./package.json
+→  Reading tsconfig from ./tsconfig.json
+→  Cleaning up outDir...
+→  Determining entrypoints...
+   ╔════════════╤════════════════╗
+   ║ Subpath    │ Entrypoint     ║
+   ╟────────────┼────────────────╢
+   ║ "my-pkg"   │ ./src/index.ts ║
+   ╚════════════╧════════════════╝
+→  Resolved build paths:
+   ╔══════════╤════════════════╗
+   ║ Location │ Resolved pathh ║
+   ╟──────────┼────────────────╢
+   ║ rootDir  │ ./src          ║
+   ║ outDir   │ ./dist         ║
+   ╚══════════╧════════════════╝
+→  Package is an ES module (package.json#/type is "module")
+→  Building CJS... (rewriting .ts -> .cjs/.d.cts)
+→  Building ESM...
+→  Updating package.json#/exports...
+→  Updating package.json#/bin...
+→  Build complete! ✅
+```
+
+Alernatively, add a `"build"` script to your `package.json`:
+
+```diff
+{
+  // ...
+  "scripts": {
++   "build": "zshy"
+  }
 }
 ```
 
-More complicated packages can specify subpaths or wildcard exports with `"zshy.exports"`:
+Then, to run a build:
+
+```bash
+$ npm run build
+```
+
+<br/>
+<br/>
+
+<h2 align="center">Usage</h2>
+
+<br/>
+
+### Flags
+
+```sh
+$ npm zshy --help
+Usage: zshy [options]
+
+Options:
+  -h, --help             Show this help message
+  -p, --project <path>   Path to tsconfig (default: ./tsconfig.json)
+      --verbose          Enable verbose output
+      --dry-run          Don't write any files or update package.json
+```
+
+<br/>
+
+### Subpaths and wildcards
+
+Multi-entrypoint packages can specify subpaths or wildcard exports with `package.json#/zshy/exports`:
 
 ```jsonc
 {
@@ -93,78 +208,115 @@ More complicated packages can specify subpaths or wildcard exports with `"zshy.e
 }
 ```
 
-<br/>
+<details>
+<summary>View typical build output</summary>
 
-### 3. Run a build
+When you run a build, you'''ll see something like this:
 
 ```bash
 $ npx zshy
 
-💎 Starting zshy build...
-⚙️ Detected project root: /path/to/my-pkg
-📦 Reading package.json from ./package.json
-📁 Reading tsconfig from ./tsconfig.json
-➡️ Determining entrypoints...
+→  Starting zshy build... 🐒
+→  Detected project root: /path/to/my-pkg
+→  Reading package.json from ./package.json
+→  Reading tsconfig from ./tsconfig.json
+→  Determining entrypoints...
    ╔════════════════════╤═════════════════════════════╗
    ║ Subpath            │ Entrypoint                  ║
    ╟────────────────────┼─────────────────────────────╢
    ║ "my-pkg"           │ ./src/index.ts              ║
-   ╟────────────────────┼─────────────────────────────╢
    ║ "my-pkg/utils"     │ ./src/utils.ts              ║
-   ╟────────────────────┼─────────────────────────────╢
    ║ "my-pkg/plugins/*" │ ./src/plugins/* (5 matches) ║
    ╚════════════════════╧═════════════════════════════╝
-📂 Transpiling from ./src (rootDir) to ./dist (outDir)
-🟨 Package is ES module (package.json#type is "module")
-🧱 Building CJS... (rewriting .ts -> .cjs/.d.cts)
-🧱 Building ESM...
-📦 Updating package.json exports...
-   {
-     ".": {
-       "types": "./out/index.d.cts",
-       "import": "./out/index.js",
-       "require": "./out/index.cjs"
-     },
-     "./utils": {
-       "types": "./out/utils.d.cts",
-       "import": "./out/utils.js",
-       "require": "./out/utils.cjs"
-     },
-     "./plugins/*": {
-       "import": "./out/src/plugins/*",
-       "require": "./out/src/plugins/*"
-     }
-   }
-🎉 Build complete!
+→  Resolved build paths:
+   ╔══════════╤════════════════╗
+   ║ Location │ Resolved pathh ║
+   ╟──────────┼────────────────╢
+   ║ rootDir  │ ./src          ║
+   ║ outDir   │ ./dist         ║
+   ╚══════════╧════════════════╝
+→  Package is ES module (package.json#/type is "module")
+→  Building CJS... (rewriting .ts -> .cjs/.d.cts)
+→  Building ESM...
+→  Updating package.json exports...
+→  Build complete! ✅
 ```
 
-Alernatively, add a `"build"` script to your `package.json`:
+And the generated `"exports"` map will look like this:
 
 ```diff
+// package.json
 {
   // ...
-  "scripts": {
-+   "build": "zshy"
++ "exports": {
++   ".": {
++     "types": "./dist/index.d.cts",
++     "import": "./dist/index.js",
++     "require": "./dist/index.cjs"
++   },
++   "./utils": {
++     "types": "./dist/utils.d.cts",
++     "import": "./dist/utils.js",
++     "require": "./dist/utils.cjs"
++   },
++   "./plugins/*": {
++     "types": "./dist/src/plugins/*",
++     "import": "./dist/src/plugins/*",
++     "require": "./dist/src/plugins/*"
++   }
++ }
+}
+```
+
+</details>
+
+<br/>
+
+### Building CLIs (`"bin"` support)
+
+If your package is a CLI, specify your CLI entrypoint in `package.json#/zshy/bin`. `zshy` will include this entrypoint in your builds and automatically set `"bin"` in your package.json.
+
+```jsonc
+{
+  // package.json
+  "name": "my-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "zshy": {
+    "bin": "./src/cli.ts" // 👈 specify CLI entrypoint
   }
 }
 ```
 
-Then, to run a build:
+When you run `zshy`, it will automatically add the appropriate `"bin"` field to your `package.json`:
 
-```bash
-$ npm run build
+```diff
+{
+  // package.json
+  "name": "my-cli",
+  "version": "1.0.0",
+  "zshy": {
+    "exports": "./src/index.ts",
+    "bin": "./src/cli.ts"
+  },
++ "bin": {
++   "my-cli": "./dist/cli.cjs" // CLI entrypoint
++ }
+}
 ```
 
+<br/>
 
 <br/>
 <br/>
-<h2 align="center">FAQ</h2>
+
+<h2 align="center">FAQ for nerds</h2>
 
 <br/>
 
 ### How does `zshy` resolve entrypoints?
 
-It reads your `package.json#zshy` config:
+It reads your `package.json#/zshy` config:
 
 ```jsonc
 // package.json
@@ -214,72 +366,82 @@ No. You can organize your source however you like; `zshy` will transpile your en
 
 ### What files does `zshy` create?
 
-It depends on your `package.json#type` field. If your package is ESM (that is, `"type": "module"` in `package.json`), the CJS build files will be generated as `.cjs`/`.d.cts`:
+It depends on your `package.json#/type` field. If your package is ESM (that is, `"type": "module"` in `package.json`):
 
 - `.js` + `.d.ts` (ESM)
 - `.cjs` + `.d.cts` (CJS)
 
 ```bash
-$ tree out
+$ tree dist
 
 .
 ├── package.json # if type == "module"
 ├── src
 │   └── index.ts
-└── out
-    ├── index.js 
+└── dist
+    ├── index.js
     ├── index.d.ts
     ├── index.cts
     └── index.d.cts
 ```
 
-Otherwise, the package is considered *default-CJS* and the ESM build files will be rewritten as `.mjs`/`.d.mts`.
+Otherwise, the package is considered _default-CJS_ and the ESM build files will be rewritten as `.mjs`/`.d.mts`.
 
 - `.mjs` + `.d.mts` (ESM)
 - `.js` + `.d.ts` (CJS)
 
 ```bash
-$ tree out
+$ tree dist
 .
 ├── package.json # if type != "module"
 ├── src
 │   └── index.ts
-└── out
+└── dist
     ├── index.js
     ├── index.d.ts
     ├── index.mjs
     └── index.d.mts
 ```
 
-> **Comparison** — `tshy` generates plain `.js`/`.d.ts` files into separate `dist/esm` and `dist/cjs` directories, each with a stub `package.json` to enable proper module resolution in Node.js. This is more convoluted than the flat file structure generated by `zshy`. It also causes issues with [Module Federation](https://github.com/colinhacks/zod/issues/4656). 
+> **Comparison** — `tshy` generates plain `.js`/`.d.ts` files into separate `dist/esm` and `dist/cjs` directories, each with a stub `package.json` to enable proper module resolution in Node.js. This is more convoluted than the flat file structure generated by `zshy`. It also causes issues with [Module Federation](https://github.com/colinhacks/zod/issues/4656).
 
 <br/>
 
 ### How does extension rewriting work?
 
-`zshy` uses the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to perform extension rewriting during the `tsc` build process. TypeScript provides dedicated hooks for performing such transforms (though they are criminally under-utilized, until now!):
+`zshy` uses the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to rewrite file extensions during the `tsc` build process. This makes it possible to generate CJS and ESM build outputs side-by-side.
+
+Depending on the build format being targeted, `zshy` will:
+
+- Rewrite `.ts` imports/exports to `.js`/`.cjs`/`.mjs`
+- Rewrite extensionless imports/exports to `.js`/`.cjs`/`.mjs`
+- Rewrite `.js` imports/exports to `.cjs`/`.mjs`
+- Rename build output files to `.cjs`/`.mjs`/`.d.cts`/`.d.mts`
+
+TypeScript provides dedicated hooks for performing such transforms (though they are criminally under-utilized).
 
 - **`ts.TransformerFactory`**: Provides AST transformations to rewrite import/export extensions before module conversion
 - **`ts.CompilerHost#writeFile`**: Handles output file extension changes (`.js` → `.cjs`/`.mjs`)
 
-> **Comparison** — `tshy` was designed to enable dual-package builds powered by the `tsc` compiler. To make this work, it relies on a specific file structure and the creation of temporary `package.json` files to accommodate the various idiosyncrasies of Node.js module resolution. TypeScript provides a robust API for AST transformations (`ts.TransformerFactory`) that `tshy` does not take advantage of.
+> **Comparison** — `tshy` was designed to enable dual-package builds powered by the `tsc` compiler. To make this work, it relies on a specific file structure and the creation of temporary `package.json` files to accommodate the various idiosyncrasies of Node.js module resolution. It also requires the use of separate `dist/esm` and `dist/cjs` build subdirectories.
 
 <br/>
 
 ### Can I use extension-less imports?
 
-Yes! `zshy` supports whatever import style you prefer: 
+Yes! `zshy` supports whatever import style you prefer:
+
 - `from "./utils"`: classic extensionless imports
 - `from "./utils.js"`: ESM-friendly extensioned imports
 - `from "./util.ts"`: recently supported natively via[`rewriteRelativeImportExtensions`](https://www.typescriptlang.org/tsconfig/#rewriteRelativeImportExtensions)
 
-Use whatever you like; `zshy` will rewrite extensionless and `.ts` imports/exports to have the appropriate file extension.
+Use whatever you like; `zshy` will rewrite all imports/exports properly during the build process.
 
 > **Comparison** — `tshy` forces you to use `.js` imports throughout your codebase. While this is generally a good practice, it's not always feasible, and there are hundreds of thousands of existing TypeScript codebases reliant on extensionless imports.
 
 <br/>
 
-### How does it generate `package.json#exports`?
+### What about `package.json#/exports`?
 
 Your exports map is automatically written into your `package.json` when you run `zshy`. The generated exports map looks like this:
 
@@ -294,18 +456,18 @@ Your exports map is automatically written into your `package.json` when you run
   },
 + "exports": { // auto-generated by zshy
 +   ".": {
-+     "types": "./out/index.d.cts",
-+     "import": "./out/index.js",
-+     "require": "./out/index.cjs"
++     "types": "./dist/index.d.cts",
++     "import": "./dist/index.js",
++     "require": "./dist/index.cjs"
 +   },
 +   "./utils": {
-+     "types": "./out/utils.d.cts", 
-+     "import": "./out/utils.js",
-+     "require": "./out/utils.cjs"
++     "types": "./dist/utils.d.cts",
++     "import": "./dist/utils.js",
++     "require": "./dist/utils.cjs"
 +   },
 +   "./plugins/*": {
-+     "import": "./out/src/plugins/*",
-+     "require": "./out/src/plugins/*"
++     "import": "./dist/src/plugins/*",
++     "require": "./dist/src/plugins/*"
 +   }
 + }
 }
@@ -324,7 +486,7 @@ import mod from "pkg";         ^^^^^
 //              ^ The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("pkg")' call instead.
 ```
 
-By having `"types"` point to the `.d.cts` declarations, this error will never happen. Technically, we're lying to TypeScript and telling it to always assume our code is CommonJS; in practice, this has no real consequences and maximizes compatibility. To learn more, read the ["Masquerading as ESM"](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseESM.md) and ["Masquerading as CJS"](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md) writeups from Are The Types Wrong. 
+By having `"types"` point to the `.d.cts` declarations, this error will never happen. Technically, we're lying to TypeScript and telling it to always assume our code is CommonJS; in practice, this has no real consequences and maximizes compatibility. To learn more, read the ["Masquerading as ESM"](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseESM.md) and ["Masquerading as CJS"](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md) writeups from Are The Types Wrong.
 
 > **Comparison** — `tshy` generates independent (but identical) `.d.ts` files in `dist/esm` and `dist/cjs`. This can cause [Excessively Deep](https://github.com/colinhacks/zod/issues/4422) errors if users of the library use declaration merging (`declare module {}`) for plugins/extensions. [Zod](https://github.com/colinhacks/zod), [day.js](https://day.js.org/), and others rely on this pattern for plugins.
 
@@ -332,25 +494,33 @@ By having `"types"` point to the `.d.cts` declarations, this error will never ha
 
 ### Can it support React Native legacy or non-Node.js environments?
 
-Yes! This is one of the key reasons `zshy` was originally developed for Zod. 
+Yes! This is one of the key reasons `zshy` was originally developed. Many environments don't support `package.json#/exports` yet:
 
-Many environments don't support `package.json#exports` yet (React Native, older bundlers, Node.js v10 or earlier, and many TypeScript projects using legacy configs). This causes issues for packages that want to use subpath imports to structure their package. Fortunately `zshy` unlocks a workaround I call a *flat build*:
+- Node.js v12.7 or earlier
+- React Native - The Metro bundler does not support `"exports"` by default
+- TypeScript projects with legacy configs — e.g. `"module": "commonjs"`
+
+This causes issues for packages that want to use subpath imports to structure their package. Fortunately `zshy` unlocks a workaround I call a _flat build_:
 
 1. Remove `"type": "module"` from your `package.json` (if present)
 2. Put your source files in your package root (not in a `src` directory)
 3. Set `outDir: "."` in your `tsconfig.json`
+4. Configure `"exclude"` in `package.json` to exclude all source files:
 
-With this setup, your build outputs (`index.js`, etc) will be written to disk right next to their corresponding source files. This lets you simulate subpath imports; imports like `"your-library/utils"` will generally resolve to `"your-library/utils/index.js"` in environments that predate modern module resolution. Zod uses this approach for broader compatibility with the following environments:
+   ```jsonc
+   {
+     // ...
+     "exclude": ["**/*.ts", "**/*.tsx", "**/*.cts", "**/*.mts", "node_modules"]
+   }
+   ```
 
-1. **Node.js v12.7 or older**
-2. **TypeScript projects using legacy configs** - e.g. `"module": "commonjs"`
-3. **React Native** - The Metro bundler does not support `"exports"` by default 
+With this setup, your build outputs (`index.js`, etc) will be written to disk alongside to their corresponding source files. Older environments will resolve imports like `"your-library/utils"` to `"your-library/utils/index.js"`, effectively simulating subpath imports in environments that don't support them.
 
-<br/> 
+<br/>
 
 ### Is it fast?
 
-Not really. Typechecking with `tsc` is a lot slower than using a bundler that strips types. That said: 
-1) you *should* be type checking your code during builds, 
-2) TypeScript is [about to get 10x faster](https://devblogs.microsoft.com/typescript/typescript-native-port/), and 
-3) you just spent the last hour staring at a Cursor spinner anyway 😇
+Not really. It uses `tsc` to typecheck your codebase, which is a lot slower than using a bundler that strips types. That said:
+
+1. You _should_ be type checking your code during builds
+2. TypeScript is [about to get 10x faster](https://devblogs.microsoft.com/typescript/typescript-native-port/)