RFC: Modernize the monorepo (ESM-only, TypeScript, pnpm, vitest, Node 22+)

[productdevbook]

Closes #2871
Closes #2353
Closes #2137
Closes #2662
Closes #1796
Closes #3492
Closes #2763
Closes #1930
Closes #3641
Closes #3487

Hi Brian — first off, thank you for ~15 years of node-postgres (and for the fact that you're still actively maintaining it — the recent v8.20 release is proof). It's been the backbone of countless projects.

This PR is intentionally large and I'm opening it as an RFC / proof-of-concept, not as something I expect to merge as-is. The aim is to share a working implementation of what a modernized node-postgres monorepo could look like, so it can serve as a concrete starting point for discussion (or get cherry-picked piece by piece, or rejected outright — all fair).

This is still active work in progress on my side. I'll keep pushing fixes here so the diff stays current.

I rebuilt the monorepo end-to-end to match the toolchain I use across my own libraries (etiket, hucre, misina, sumak). The branch is at https://github.com/productdevbook/ts-node-postgres/tree/feat/modernize-esm-ts-vitest if you'd rather just browse the diff there.

What changed at a glance

Area	Before	After
Module system	CJS + thin ESM wrappers	ESM-only ("type": "module")
Node baseline	>= 16	>= 22.11
Package manager	yarn + lerna	pnpm 10 workspaces
TypeScript	4.0.3 (3 packages)	6.x everywhere
Build	tsc --build	obuild (transform → .mjs + .d.mts)
Lint / format	eslint + prettier	oxlint + oxfmt
Test	mocha + chai + Makefile	vitest (flat test/ per package)
Typecheck	tsc	tsgo (@typescript/native-preview)
Versioning	lerna independent	bumpp -r + changelogithub
Imports	require('./x')	import { x } from './x.ts' (per misina convention)
Exports	main / types	granular subpath exports map (./client, ./pool, ./driver/*, …)

Per-package status

All 8 packages converted (lib/ → src/, JS → TS, mocha → vitest):

• pg → 9.0.0 — 133 JS files ported to TS, src/ split into client/, connection/, query/, types/, crypto/, native/, utils. Public surface preserved (Client, Pool, Connection, types, DatabaseError, defaults, Query, Result).
• pg-pool → 4.0.0 — single-file CJS rewritten as a typed Pool class.
• pg-cursor → 3.0.0
• pg-query-stream → 5.0.0 — already TS, tightened strict mode.
• pg-protocol → 2.0.0 — already TS, ESM-only output.
• pg-cloudflare → 2.0.0 — workerd condition preserved; non-workerd fallback ships a no-op CloudflareSocket with the same public shape so consumers can import { CloudflareSocket } from any runtime.
• pg-connection-string → 3.0.0 — JS + .d.ts fused into a single TS module.
• pg-native → 4.0.0 — libpq binding still works via ESM default import.

Issues this addresses

If this lands (in any form), the following long-standing issues become resolvable:

• Migrating some packages to TypeScript. #2871 — Migrating some packages to TypeScript (umbrella tracker)
• Add ESM support #2353 — Add ESM support
• Add support for native ESM modules  #2137 — Add support for native ESM modules
• Rewrite in TypeScript #2662 — Rewrite in TypeScript
• Merge TypeScript declarations into repo #1796 — Merge TypeScript declarations into repo (TS source means types are intrinsic, no more @types/pg drift)
• Query callbacks have incorrect type definitions #1930 — Query callbacks have incorrect type definitions
• TypeScript: how to import the NoticeMessage type? #2763 — TypeScript: how to import the NoticeMessage type? (granular subpath exports: `pg-protocol/messages`)
• Cannot find module 'pg-protocol/dist/messages' or its corresponding type declarations. #3492 — Cannot find module 'pg-protocol/dist/messages' or its corresponding type declarations
• Publish pg@9 to JSR #3641 — Publish pg@9 to JSR (now JSR-publishable)
• Bind does not generate the result column format encoding in pg-protocol #3487 — Binary-mode INT[] roundtrip returning empty array (fixed during the migration; was a real regression in the JS→TS port of Result#parseRow)

Open / superseded PRs in flight

• Upgrade eslint and typescript #3662 — "Upgrade eslint and typescript" → eslint replaced by oxlint, TS bumped to 6.x; superseded.
• build(deps-dev): bump lerna from 3.22.1 to 9.0.7 #3646 — "build(deps-dev): bump lerna 3 → 9" → lerna removed entirely; obsolete.
• build(deps-dev): bump eslint-plugin-prettier from 5.5.1 to 5.5.5 #3648 — "build(deps-dev): bump eslint-plugin-prettier" → eslint+prettier replaced; obsolete.

I haven't touched #3168 ("build pg-cloudflare as a CommonJS module") because it's solving the same Workers test issue from the opposite direction — that ticket can stay open as a fallback if this RFC isn't the path forward.

Verification

GitHub Actions: Lint & Typecheck pass · Test (Node 22) pass · Test (Node 24) pass. Locally with the included docker-compose:

corepack enable
pnpm install
docker compose up -d
set -a && source .env.test && set +a
pnpm typecheck   # 0 errors
pnpm lint        # 0 errors, 0 warnings
pnpm build       # 8/8 packages emit .mjs + .d.mts
pnpm test        # exit 0

Package	Pass / Total
pg-protocol	73/73
pg-connection-string	71/71
pg-cloudflare	6/6
pg-native	75/75
pg-pool	85/85 (2 native-only skipped)
pg-cursor	37/37
pg-query-stream	40/40
pg	426/426 (6 native-only skipped)
pg-esm-test	22/22
Total	835/835 (8 platform-skipped)

`pnpm test` exits 0 cleanly — lint, typecheck, build and the full suite all pass.

Remaining skips

The 8 skipped tests are all native-only paths gated on the optional `pg-native` peer being present. They do execute (and pass) on CI thanks to the `libpq-dev` install + `pnpm rebuild libpq` step in `.github/workflows/ci.yml`; the per-test skips guard the cases where individual native-client wiring would otherwise fail when the dependency wasn't loaded.

Local infra added

• `docker-compose.yml` — postgres-ssl service with healthcheck.
• `scripts/init-scram.sql` — bootstraps the SCRAM test role the integration suite expects.
• `.env.test` — convenience env file (`set -a && source .env.test`).

Breaking changes (intentional)

• CJS consumers are broken. require('pg') no longer works. This is the core trade-off of going ESM-only. Major-version bump for every package reflects that.
• engines.node >= 22.11. Node 16/18/20 dropped.
• Bundle layout changed from dist/index.js (CJS) to dist/index.mjs + dist/index.d.mts.
• Several internal modules now have explicit subpath exports; users reaching into pg/lib/... will need to update.

Why I'm sending this

I wanted to put a working, end-to-end modernization on the table rather than just opinions on Twitter. If any of this is useful — even just the workflow files or one package's conversion — please cherry-pick freely. If the ESM-only direction isn't where you want node-postgres to go, that's a totally fair answer; closing this PR doesn't bother me.

Happy to break it up into smaller, more reviewable PRs (per package, or just the tooling), to host the result as a fork under a different name, or to walk through any specific decision. Whatever's least friction for you.

— Wind (@productdevbook)

---

PS: I'm currently looking for a full-stack role — CV / portfolio: https://productdevbook.com 🙂

🤖 Generated with Claude Code

[brianc]

Holy smokes this is amazing. I am looking forward to looking this over. I'm just wrapping up some final travel - took a bit of a sabbatical after work, then will dive head first into node-postgres soon! Def not stepping back, just needed a computer break after doing the startup sprint stuff for years on end.

[james-pre]

Might I suggest sticking with regular typescript for now? @typescript/native-preview is only temporary and TS 7.0 will use the native port for tsc. Staying with the regular typescript package would decrease maintaince burden and dependency churn.

Also for pg@9 I'm hoping #3663 makes the cut.

[1valdis]

CJS consumers are broken. require('pg') no longer works.

If packages don't have top-level await, it's possible to make them require-able even if they are ES modules. Node supports require(ESM) for quite some time now. This works via

 "exports": {
   ".": {
     "types": "./path-to-es-module.d.ts",
     "import": "./path-to-es-module.js",
+    "module-sync": "./path-to-es-module.js"
   }
}

and it's the way I use for a ESM-only library that I maintain.

import { x } from './x.ts'

I wonder why this is necessary instead of .js imports. The only pro I see is it looks kind of more beautiful but if you work with TypeScript for years then you know .js takes no additional compiler and dev environment settings and is much more likely to "just work".

[james-pre]

Note sure how relavent it is, for moduleResolution: NodeNext, having .js in imports and exports is required. For projects I maintain (which are ESM), I use TS' verbatimModuleSyntax and use .js extensions in the TS source. For example import { Duck } from './duck.js'; inside index.ts.