| 1 |
# Upgrade a plugin package to ESM-only (packages/<name>) |
| 2 |
|
| 3 |
Upgrade a single plugin under `packages/<name>` to publish ESM-only output with TypeScript-emitted JS and declarations. |
| 4 |
|
| 5 |
## Prerequisites |
| 6 |
|
| 7 |
- Repo already contains shared config at `.config/tsconfig.base.json` and `.config/tsconfig.plugin.json` and (optionally) `.config/vitest.config.mts` from prior migrations. |
| 8 |
- Scope constraint: make changes only inside the target package directory (e.g., `packages/alias`). Do not add or edit files outside `packages/<name>`. |
| 9 |
- Local Node 20.19+ to run builds and tests. |
| 10 |
|
| 11 |
## Steps |
| 12 |
|
| 13 |
1. Identify the target package |
| 14 |
|
| 15 |
- Set a shell variable for reuse: `PKG=packages/<name>`. |
| 16 |
|
| 17 |
2. Package metadata: ESM-only and minimums |
| 18 |
|
| 19 |
- Edit `$PKG/package.json`: |
| 20 |
|
| 21 |
- Set `"type": "module"`. |
| 22 |
- Replace legacy `main/module/exports.require` with an ESM-only export mapped via the explicit `"."` entry for broad tooling compatibility: |
| 23 |
```json |
| 24 |
{ |
| 25 |
"exports": { |
| 26 |
".": { |
| 27 |
"types": "./dist/index.d.ts", |
| 28 |
"import": "./dist/index.js", |
| 29 |
"default": "./dist/index.js" |
| 30 |
} |
| 31 |
}, |
| 32 |
"types": "./dist/index.d.ts" |
| 33 |
} |
| 34 |
``` |
| 35 |
- Set minimums: `"engines": { "node": ">=20.19.0" }` and `"peerDependencies": { "rollup": ">=4.0.0" }`. |
| 36 |
- Keep `rollup` as a devDependency only if tests use it. Otherwise remove it. |
| 37 |
- Ensure published files include build output and standard docs: |
| 38 |
```json |
| 39 |
"files": ["dist", "README.md", "LICENSE"] |
| 40 |
``` |
| 41 |
Notes: |
| 42 |
- `package.json` `files` does not support negation patterns. If an existing `package.json` contains "files": [ ..., "!dist/**/*.map", ... ], remove the negated entry—negation is not supported and will be ignored. |
| 43 |
- Always publish source maps. Do not exclude `dist/**/*.map` via `.npmignore`, and do not disable `sourceMap`/`declarationMap` for published packages. If a package currently excludes maps (via `.npmignore` or tsconfig), remove those exclusions so maps are included. |
| 44 |
|
| 45 |
3. Build scripts: TypeScript emit to dist |
| 46 |
|
| 47 |
- Prefer a tsc-only build for packages that do not need bundling: |
| 48 |
- In `$PKG/package.json`, set scripts: |
| 49 |
```json |
| 50 |
"prebuild": "del-cli dist", |
| 51 |
"build": "tsc --project tsconfig.json", |
| 52 |
"pretest": "pnpm build", |
| 53 |
"prerelease": "pnpm build", |
| 54 |
"prepare": "if [ ! -d 'dist' ]; then pnpm build; fi" |
| 55 |
``` |
| 56 |
- If this package still needs bundling for tests/examples, keep its Rollup config but point inputs at the TypeScript output in `dist/` instead of sources. |
| 57 |
|
| 58 |
4. TypeScript config: use the shared plugin config (symlink) |
| 59 |
|
| 60 |
- Replace any existing `$PKG/tsconfig.json` with a symlink to the shared plugin config (`.config/tsconfig.plugin.json`), which already enables emit to `dist/` and declaration maps: |
| 61 |
```bash |
| 62 |
# from repo root |
| 63 |
ln -snf ../../.config/tsconfig.plugin.json "$PKG/tsconfig.json" |
| 64 |
git add "$PKG/tsconfig.json" |
| 65 |
``` |
| 66 |
On Windows PowerShell, you can run: |
| 67 |
```powershell |
| 68 |
# from repo root |
| 69 |
$pkg = 'packages/<name>' |
| 70 |
New-Item -ItemType SymbolicLink -Path "$pkg/tsconfig.json" -Target (Resolve-Path ".config/tsconfig.plugin.json") -Force |
| 71 |
git add "$pkg/tsconfig.json" |
| 72 |
``` |
| 73 |
The shared config content lives at `.config/tsconfig.plugin.json`. |
| 74 |
- Delete any package-local `rollup` build scripts that produced CJS, and remove any `types/` folder if declarations were hand-authored (they will now be generated). |
| 75 |
|
| 76 |
5. Source: convert to pure ESM and modern Node APIs |
| 77 |
|
| 78 |
- Replace `require`, `module.exports`, and `__dirname` patterns with ESM equivalents. |
| 79 |
- Use `node:` specifiers for built-ins (e.g., `import path from 'node:path'`). |
| 80 |
- Prefer the latest ES APIs: use `import.meta.dirname` and `import.meta.filename` (Node ≥20.11) instead of re‑creating them via `fileURLToPath`. |
| 81 |
|
| 82 |
```ts |
| 83 |
import path from 'node:path'; |
| 84 |
|
| 85 |
const here = import.meta.dirname; |
| 86 |
// const file = import.meta.filename; |
| 87 |
const pkgJson = path.join(here, 'package.json'); |
| 88 |
``` |
| 89 |
|
| 90 |
Use URL utilities only when specifically needed (e.g., for non‑file module URLs): `fileURLToPath(new URL('.', import.meta.url))`. |
| 91 |
|
| 92 |
- Inline and export public types from `src/index.ts`; avoid separate `types/` unless unavoidable. |
| 93 |
- Conversion rules for file types: |
| 94 |
- Always convert any `.js` in `src/` to `.ts`. |
| 95 |
- Never convert files in test `fixtures/` to TypeScript—keep fixtures exactly as authored. |
| 96 |
- Always convert any `.js` in `test/` to `.ts` (test sources only; exclude `test/**/fixtures/**`). |
| 97 |
|
| 98 |
6. Tests: order of operations (AVA → Vitest) and ESM |
| 99 |
|
| 100 |
- Remove CJS-specific branches/assertions from tests. |
| 101 |
- Follow this sequence for reliability: |
| 102 |
1. After JS→TS conversion in `src/` and `test/` and after any `package.json` changes, always run the AVA test suite. |
| 103 |
2. Only after verifying AVA tests run without modifications, convert the AVA tests to Vitest. |
| 104 |
3. After converting tests to Vitest, always run the Vitest suite after any subsequent `src/` change. |
| 105 |
- Note: If a package already uses Vitest, start at step 3 and skip AVA‑specific steps. |
| 106 |
- Ensure Rollup bundles created in tests are `await bundle.close()`-d to avoid leaks. |
| 107 |
|
| 108 |
7. Clean up package artifacts |
| 109 |
- Remove obsolete files that are no longer used by ESM-only publishing (examples): |
| 110 |
- `$PKG/rollup.config.*` if switching to tsc-only. |
| 111 |
- `$PKG/types/**` once declarations are generated to `dist/`. |
| 112 |
|
| 113 |
## Verify |
| 114 |
|
| 115 |
- Build succeeds and emits JS and d.ts to `dist/`: |
| 116 |
```bash |
| 117 |
pnpm -C $PKG build |
| 118 |
tree $PKG/dist | sed -n '1,80p' |
| 119 |
``` |
| 120 |
- Symlink exists and points at the shared config: |
| 121 |
```bash |
| 122 |
test -L "$PKG/tsconfig.json" && ls -l "$PKG/tsconfig.json" || (echo "tsconfig.json symlink missing" && exit 1) |
| 123 |
``` |
| 124 |
- Type declarations resolve for consumers: |
| 125 |
```bash |
| 126 |
jq -r '.types, .exports["."].types, .exports["."].import' $PKG/package.json |
| 127 |
``` |
| 128 |
- Runtime smoke (Node ESM import works): |
| 129 |
```bash |
| 130 |
node -e "import('file://$PWD/$PKG/dist/index.js').then(() => console.log('ok'))" |
| 131 |
``` |
| 132 |
- Tests pass for the package (runner may be AVA or Vitest depending on the package): |
| 133 |
```bash |
| 134 |
pnpm -C $PKG test |
| 135 |
``` |
| 136 |
|
| 137 |
## Rollback |
| 138 |
|
| 139 |
- Revert the package directory to the previous commit (modern Git): |
| 140 |
```bash |
| 141 |
git restore -SW $PKG |
| 142 |
``` |
| 143 |
- If needed, `git reset --hard HEAD~1` when this package’s change is isolated on a feature branch. |
| 144 |
|
| 145 |
## References |
| 146 |
|
| 147 |
- Alias migration (ESM-only) — PR #1926: feat(alias)!: ESM only. Update Node and Rollup minimum versions |
| 148 |
- Task spec used for alias — Issue #1925 |
| 149 |
- Shared TS configs used by packages — `.config/tsconfig.base.json`, `.config/tsconfig.plugin.json` |