zshy 0.0.9 → 0.0.11

package/README.md

@@ -39,13 +39,13 @@
 ### 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`
-- 🟦 **No config file** — Reads only from your `package.json` and `tsconfig.json` (configurable)
+- 👑 **Powered by `tsc`** — The gold standard for TypeScript transpilation
+- 📦 **Bundler-free** — No bundler or bundler configs involved
+- 🟦 **No config file** — Reads from your `package.json` and `tsconfig.json`
 - 📝 **Declarative entrypoint map** — Specify your TypeScript entrypoints in `package.json#/zshy`
 - 🤖 **Auto-generated `"exports"`** — Writes `"exports"` map directly into your `package.json`
 - 🐚 **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`
+- 📂 **Unopinionated** — Use any file structure or import extension syntax you like
 - ⚛️ **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).
@@ -55,42 +55,6 @@
 <br/>
 <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/>
@@ -105,15 +69,15 @@ pnpm add --save-dev zshy
 
 <br/>
 
-### 2. Add the `"zshy"` field to your `package.json`
-
-Specify your package entrypoint with the `"zshy"` key in `package.json`.
+### 2. Specify your entrypoint(s) in `package.json#zshy`:
 
-```jsonc
+```diff
 {
   "name": "my-pkg",
   "version": "1.0.0",
-  "zshy": "./src/index.ts" // 👈 package entrypoint
++ "zshy": {
++   ".": "./src/index.ts"
++ }
 }
 ```
 
@@ -121,8 +85,10 @@ Specify your package entrypoint with the `"zshy"` key in `package.json`.
 
 ### 3. Run a build
 
+Run a build with `npx zshy`:
+
 ```bash
-$ npx zshy
+$ npx zshy # use --dry-run to try it out without writing/updating files
 
 →  Starting zshy build 🐒
 →  Detected project root: /Users/colinmcd94/Documents/projects/zshy
@@ -137,7 +103,7 @@ $ npx zshy
    ╚════════════╧════════════════╝
 →  Resolved build paths:
    ╔══════════╤════════════════╗
-   ║ Location │ Resolved pathh ║
+   ║ Location │ Resolved path  ║
    ╟──────────┼────────────────╢
    ║ rootDir  │ ./src          ║
    ║ outDir   │ ./dist         ║
@@ -150,22 +116,80 @@ $ npx zshy
 →  Build complete! ✅
 ```
 
-Alernatively, add a `"build"` script to your `package.json`:
+> **Add a `"build"` script to your `package.json`**
+>
+> ```diff
+> {
+>   // ...
+>   "scripts": {
+> +   "build": "zshy"
+>   }
+> }
+> ```
+>
+> Then, to run a build:
+>
+> ```bash
+> $ npm run build
+> ```
+
+<br/>
+
+<br/>
+
+<h2 align="center">How it works</h2>
+
+Vanilla `tsc` does not perform _extension rewriting_; it will only ever transpile a `.ts` file to a `.js` file (never `.cjs` or `.mjs`). This is the fundamental limitation that forces library authors to use bundlers or bundler-powered tools like `tsup`, `tsdown`, or `unbuild`...
+
+...until now! `zshy` works around this limitation using the official [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API), which provides some powerful (and criminally under-utilized) hooks for customizing file extensions during the `tsc` build process.
+
+Using these hooks, `zshy` transpiles each `.ts` file to `.js/.d.ts` (ESM) and `.cjs/.d.cts` (CommonJS):
+
+```bash
+$ tree .
+├── package.json
+├── src
+│   └── index.ts
+└── dist # generated
+  ├── index.js
+  ├── index.cjs
+  ├── index.d.ts
+  └── index.d.cts
+```
+
+Similarly, all relative `import`/`export` statements are rewritten to include the appropriate file extension. (Other tools like `tsup` or `tsdown` do the same, but they require a bundler to do so.)
+
+| 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"` |
+
+Finally, `zshy` automatically writes `"exports"` into your `package.json`:
 
 ```diff
 {
   // ...
-  "scripts": {
-+   "build": "zshy"
-  }
+  "zshy": {
+    "exports": "./src/index.ts"
+  },
++ "exports": { // auto-generated by zshy
++   ".": {
++     "types": "./dist/index.d.cts",
++     "import": "./dist/index.js",
++     "require": "./dist/index.cjs"
++   }
++ }
 }
 ```
 
-Then, to run a build:
+The result is a tool that I consider to be the "holy grail" of TypeScript library build tools:
 
-```bash
-$ npm run build
-```
+- 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/>
@@ -288,7 +312,7 @@ If your package is a CLI, specify your CLI entrypoint in `package.json#/zshy/bin
 }
 ```
 
-When you run `zshy`, it will automatically add the appropriate `"bin"` field to your `package.json`:
+The `"bin"` field is automatically written into your `package.json`:
 
 ```diff
 {
@@ -300,13 +324,12 @@ When you run `zshy`, it will automatically add the appropriate `"bin"` field to
     "bin": "./src/cli.ts"
   },
 + "bin": {
-+   "my-cli": "./dist/cli.cjs" // CLI entrypoint
++   "my-cli": "./dist/cli.cjs" // CommonJS entrypoint
 + }
 }
 ```
 
 <br/>
-
 <br/>
 <br/>
 
@@ -409,16 +432,22 @@ $ tree dist
 
 ### How does extension rewriting work?
 
-`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.
+`zshy` uses the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to rewrite file extensions during the `tsc` emit step.
 
-Depending on the build format being targeted, `zshy` will:
+- If `"type": "module"`
+  - `.ts` becomes `.js`/`.d.ts` (ESM) and `.cjs`/`.d.cts` (CJS)
+- Otherwise:
+  - `.ts` becomes `.mjs`/`.d.mts` (ESM) and `.js`/`.d.ts` (CJS)
 
-- 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`
+Similarly, all relative `import`/`export` statements are rewritten to account for the new file extensions.
 
-TypeScript provides dedicated hooks for performing such transforms (though they are criminally under-utilized).
+| 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"` |
+
+TypeScript's Compiler API 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`)
@@ -479,14 +508,16 @@ Your exports map is automatically written into your `package.json` when you run
 
 The `"types"` field always points to the CJS declaration file (`.d.cts`). This is an intentional design choice.
 
-**It solves "Masquerading as ESM" issue**. Put more simply, you can always `import` a CJS package from ESM, but you can't `require` an ES module from a CJS environment. You've likely seen this dreaded error before:
+**It solves the "Masquerading as ESM" issue**. You've likely seen this dreaded error before:
 
 ```ts
 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.
+Simply put: ESM files can `require` CommonJS, but CommonJS files can't `import` ESM. By having `"types"` point to the `.d.cts` declarations, this error will never happen. Technically, we're tricking TypeScript into thinking 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.