zshy 0.0.6 → 0.0.7

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
 
-  <h1 align="center">⚜️<br/><code>zshy</code></h1>
-  <p align="center">The ultimate build tool for TypeScript libraries. Powered by <code>tsc</code>.
+  <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,14 +15,14 @@
 <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/>
@@ -34,6 +34,8 @@
 
 `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
@@ -49,8 +51,47 @@
 - 🐌 **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/>
 
@@ -83,30 +124,30 @@ Specify your package entrypoint with the `"zshy"` key in `package.json`.
 ```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...
+→  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 path ║
-   ╟──────────┼───────────────╢
-   ║ rootDir  │ ./src         ║
-   ║ outDir   │ ./out         ║
-   ╚══════════╧═══════════════╝
-🟨 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!
+→  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`:
@@ -126,6 +167,26 @@ Then, to run a build:
 $ 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
@@ -150,16 +211,16 @@ Multi-entrypoint packages can specify subpaths or wildcard exports with `package
 <details>
 <summary>View typical build output</summary>
 
-When you run a build, you'll see something like this:
+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                  ║
    ╟────────────────────┼─────────────────────────────╢
@@ -167,18 +228,18 @@ $ npx zshy
    ║ "my-pkg/utils"     │ ./src/utils.ts              ║
    ║ "my-pkg/plugins/*" │ ./src/plugins/* (5 matches) ║
    ╚════════════════════╧═════════════════════════════╝
-🔧 Resolved build paths:
-   ╔══════════╤═══════════════╗
-   ║ Location │ Resolved path ║
-   ╟──────────┼───────────────╢
-   ║ rootDir  │ ./src         ║
-   ║ outDir   │ ./out         ║
-   ╚══════════╧═══════════════╝
-🟨 Package is ES module (package.json#/type is "module")
-🧱 Building CJS... (rewriting .ts -> .cjs/.d.cts)
-🧱 Building ESM...
-📦 Updating package.json exports...
-🎉 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! ✅
 ```
 
 And the generated `"exports"` map will look like this:
@@ -189,19 +250,19 @@ And the generated `"exports"` map will look like this:
   // ...
 + "exports": {
 +   ".": {
-+     "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/*": {
-+     "types": "./out/src/plugins/*",
-+     "import": "./out/src/plugins/*",
-+     "require": "./out/src/plugins/*"
++     "types": "./dist/src/plugins/*",
++     "import": "./dist/src/plugins/*",
++     "require": "./dist/src/plugins/*"
 +   }
 + }
 }
@@ -211,15 +272,16 @@ And the generated `"exports"` map will look like this:
 
 <br/>
 
-### For CLIs (`"bin"` support)
+### 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.
 
-```json
+```jsonc
 {
   // package.json
   "name": "my-cli",
   "version": "1.0.0",
+  "type": "module",
   "zshy": {
     "bin": "./src/cli.ts" // 👈 specify CLI entrypoint
   }
@@ -238,30 +300,17 @@ When you run `zshy`, it will automatically add the appropriate `"bin"` field to
     "bin": "./src/cli.ts"
   },
 + "bin": {
-+   "my-cli": "./out/cli.js" // CLI entrypoint
++   "my-cli": "./dist/cli.cjs" // CLI entrypoint
 + }
 }
 ```
 
 <br/>
 
-### Flags
-
-```sh
-$ npm zshy --help
-Usage: zshy [options]
-
-Options:
-  -h, --help             Show this help message
-  -p, --project <path>   Path to tsconfig.json file
-      --verbose          Enable verbose output
-      --dry-run          Don't write any files or update package.json
-```
-
 <br/>
 <br/>
 
-<h2 align="center">FAQ</h2>
+<h2 align="center">FAQ for nerds</h2>
 
 <br/>
 
@@ -392,7 +441,7 @@ Use whatever you like; `zshy` will rewrite all imports/exports properly during t
 
 <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:
 
@@ -407,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/*"
 +   }
 + }
 }
@@ -449,7 +498,7 @@ Yes! This is one of the key reasons `zshy` was originally developed. Many enviro
 
 - Node.js v12.7 or earlier
 - React Native - The Metro bundler does not support `"exports"` by default
-- TypeScript projects with legacy configs — e.. `"module": "commonjs"`
+- 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_:
 
@@ -458,12 +507,12 @@ This causes issues for packages that want to use subpath imports to structure th
 3. Set `outDir: "."` in your `tsconfig.json`
 4. Configure `"exclude"` in `package.json` to exclude all source files:
 
-- ```jsonc
-  {
-    // ...
-    "exclude": ["**/*.ts", "**/*.tsx", "**/*.cts", "**/*.mts", "node_modules"]
-  }
-  ```
+   ```jsonc
+   {
+     // ...
+     "exclude": ["**/*.ts", "**/*.tsx", "**/*.cts", "**/*.mts", "node_modules"]
+   }
+   ```
 
 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.
 
@@ -473,5 +522,5 @@ With this setup, your build outputs (`index.js`, etc) will be written to disk al
 
 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;
+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/)