feat(db): support Node.js 18+ for the npm package via WASM SQLite fallback (#1260)

## Why

The npm package required Node.js 22.15+ purely because our
config/cache/auth layer depends on the built-in `node:sqlite` module,
which older runtimes don't ship. That excluded users still on Node 18/20
for no fundamental reason — the CLI's actual SQLite footprint is tiny
(prepare → get/all/run, exec, manual transactions).

A user asked for Node 20 support and proposed `better-sqlite3`. We
pushed back on that: a native addon breaks the single-file bundle,
reintroduces per-platform/per-ABI install flakiness, and violates our
zero-runtime-dependencies rule.

## Approach

Fall back to a pure-WASM driver (`node-sqlite3-wasm`) on Node < 22.15,
selected at runtime behind the existing single-file adapter:

- **22.15+** → native `node:sqlite` (unchanged fast path)
- **18–22.14** → bundled WASM driver

It's a bundled devDependency, so the single-file bundle and
no-runtime-deps guarantees both hold.

Critically, the driver is `require()`d lazily so the standalone binary
build externalizes it: the SEA binary always embeds a modern LTS Node
and uses native `node:sqlite`, making the WASM path dead code there that
adds **zero bytes** to the binary. This was the hard constraint for
taking this route over `better-sqlite3`.

## Tradeoff

The WASM fallback can't use SQLite WAL mode, so its local cache is
slower and less concurrency-friendly. Acceptable for a single-process
CLI, and the docs now steer people toward the standalone binary or Node
22.15+.

## Version floors

Dev tooling still needs 22.15+ (it runs the sources against
`node:sqlite` via tsx). So `engines.node` advertises the consumer floor
(`>=18`) while a new `devEngines` field records the development floor —
the doc generator was decoupled to keep the two independent.

CI now runs the npm-package job on a Node 20 matrix entry so the WASM
fallback is exercised, not just shipped.

Author: BYK

.github/workflows/ci.yml

@@ -39,6 +39,12 @@ env:
   # APIs). Fixed in 24.18.0 / 22.23.1 (nodejs/node#64004). A floating major
   # ("24"/"22") silently reuses the runner's pre-cached buggy patch, so pin the
   # exact patched versions here and bump them in one place.
+  #
+  # Node 20 is the WASM-SQLite floor: the npm package supports Node >= 18, and
+  # on < 22.15 (which lacks node:sqlite) it falls back to the bundled
+  # node-sqlite3-wasm driver. The npm-package job runs a Node 20 matrix entry
+  # so that fallback path is exercised in CI rather than only in production.
+  NODE_VERSION_20: "20.20.2"
   NODE_VERSION_22: "22.23.1"
   NODE_VERSION_24: "24.18.0"
 
@@ -770,23 +776,25 @@ jobs:
         run: pnpm run test:e2e
 
   build-npm:
-    name: Build npm Package (Node ${{ matrix.node }})
+    name: Build npm Package (smoke Node ${{ matrix.node }})
     needs: [lint, test-unit]
     runs-on: ubuntu-latest
     environment: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) && 'production' || '' }}
     strategy:
       fail-fast: false
       matrix:
-        node: ["22", "24"]
+        node: ["20", "22", "24"]
     steps:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v4
+      # Build under our development Node floor (22.15+). The build tooling
+      # (tsx loader hooks in script/require-shim.mjs) uses node:module APIs
+      # only present on 22.15+, so the bundle is always produced on a modern
+      # Node — matching how we actually publish. The matrix Node version is
+      # only used to *run* the produced artifact below.
       - uses: actions/setup-node@v6
         with:
-          # Matrix entries stay bare majors ("22"/"24") for the job name and the
-          # `matrix.node == '22'` artifact guard below; map each to its exact
-          # patched version from the central env block here.
-          node-version: ${{ matrix.node == '24' && env.NODE_VERSION_24 || env.NODE_VERSION_22 }}
+          node-version: ${{ env.NODE_VERSION_22 }}
       - uses: actions/cache@v5
         id: cache
         with:
@@ -799,6 +807,16 @@ jobs:
           # Environment-scoped (production) — see note in build-binary.
           SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
         run: pnpm run bundle
+      - run: npm pack
+      # Switch to the matrix Node to run the produced artifact. This is the
+      # consumer's perspective: Node 20 exercises the WASM SQLite fallback
+      # (no node:sqlite before 22.15); 22/24 use the native driver.
+      - uses: actions/setup-node@v6
+        with:
+          # Matrix entries stay bare majors ("20"/"22"/"24") for the job name
+          # and the `matrix.node == '22'` artifact guard below; map each to its
+          # exact patched version from the central env block here.
+          node-version: ${{ matrix.node == '24' && env.NODE_VERSION_24 || matrix.node == '20' && env.NODE_VERSION_20 || env.NODE_VERSION_22 }}
       - name: Smoke test (Node.js)
         run: node dist/bin.cjs --help
       - name: Smoke test (Node.js — deep)
@@ -809,7 +827,8 @@ jobs:
         run: |
           # auth status without a token exercises SQLite init, schema
           # migrations, telemetry lazy import, and the CJS require chain.
-          # Expected: exit 10 (AUTH_NOT_AUTHENTICATED), NOT a crash/syntax error.
+          # On Node 20 this runs entirely through the bundled WASM SQLite
+          # driver. Expected: exit 10 (AUTH_NOT_AUTHENTICATED), NOT a crash.
           OUTPUT=$(node dist/bin.cjs auth status 2>&1) && EXIT_CODE=$? || EXIT_CODE=$?
           if [[ $EXIT_CODE -ne 10 ]]; then
             echo "::error::Expected exit code 10 (not authenticated), got $EXIT_CODE"
@@ -821,7 +840,6 @@ jobs:
             echo "$OUTPUT"
             exit 1
           fi
-      - run: npm pack
       - name: Upload artifact
         if: matrix.node == '22'
         uses: actions/upload-artifact@v7

.lore.md

@@ -37,7 +37,7 @@ yarn global add sentry
 bun add -g sentry
 ```
 
-> The npm/pnpm/yarn packages require Node.js 22.15+.
+> The npm/pnpm/yarn packages require Node.js 18+. On Node.js 22.15+ the CLI uses the built-in `node:sqlite`; on Node.js 18–22.14 it transparently falls back to a bundled WASM SQLite driver.
 
 ### Run Without Installing
 
@@ -83,7 +83,7 @@ Credentials are stored in `~/.sentry/` with restricted permissions (mode 600).
 ## Library Usage
 
 <!-- GENERATED:START library-prereq -->
-Use Sentry CLI programmatically in Node.js (≥22.15) without spawning a subprocess:
+Use Sentry CLI programmatically in Node.js (≥18.0) without spawning a subprocess:
 <!-- GENERATED:END library-prereq -->
 
 ```typescript

README.md

@@ -211,11 +211,15 @@ Calls should be sequential (awaited one at a time).
 | **Output** | Parsed object (zero-copy) | String (needs JSON.parse) |
 | **Errors** | `SentryError` with typed fields | Exit code + stderr string |
 | **Auth** | `token` option or env vars | Env vars only |
-| **Node.js** | >=22 required | Any version |
+| **Node.js** | >=18 required | Any version |
 
 ## Requirements
 
-- **Node.js >= 22** (required for `node:sqlite`)
+- **Node.js >= 18**. On Node.js 22.15+ the built-in `node:sqlite` module is used; on Node.js 18–22.14 the CLI transparently falls back to a bundled WASM SQLite driver, so no native module or extra install step is required.
+
+:::caution
+The WASM SQLite fallback (Node.js 18–22.14) does not support [WAL mode](https://www.sqlite.org/wal.html), so concurrent access from multiple processes is slower and its local cache reads/writes are less efficient. For the best performance and reliability we **strongly recommend** the [standalone binary](/installation/) (which bundles a modern runtime) or running on **Node.js 22.15+** so the native `node:sqlite` driver is used.
+:::
 
 ## Streaming Commands
 

docs/src/content/docs/library-usage.md

@@ -340,6 +340,18 @@ await sdk.release["set-commits"]({ orgVersion: "1.0.0", auto: true });
 await sdk.release.finalize({ orgVersion: "1.0.0" });
 ```
 
+:::note
+The `sentry` npm package requires **Node.js 18+** (v3's `@sentry/cli` supported
+older runtimes). On Node.js 22.15+ it uses the built-in `node:sqlite` module; on
+Node.js 18–22.14 it transparently falls back to a bundled WASM SQLite driver, so
+no native module or extra install step is needed. The standalone binary bundles
+its own runtime and is unaffected by your installed Node.js version.
+
+For best performance we strongly recommend the standalone binary or Node.js
+22.15+ — the WASM fallback can't use SQLite WAL mode, making its local cache
+slower and less concurrency-friendly.
+:::
+
 Mapping:
 
 | v3 (`@sentry/cli`) | v4 (`sentry`) |

docs/src/content/docs/migrating-from-v3.md

@@ -43,6 +43,7 @@
     "ink-spinner": "^5.0.0",
     "jpeg-js": "^0.4.4",
     "marked": "^15.0.12",
+    "node-sqlite3-wasm": "0.8.59",
     "p-limit": "^7.3.0",
     "peggy": "^5.1.0",
     "picomatch": "^4.0.4",
@@ -75,13 +76,20 @@
   },
   "description": "Sentry CLI - A command-line interface for using Sentry built by robots and humans for robots and humans",
   "engines": {
-    "node": ">=22.15"
+    "node": ">=18.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.15"
+    }
   },
   "files": [
     "dist/bin.cjs",
     "dist/index.cjs",
     "dist/index.d.cts",
     "dist/ink-app.js",
+    "dist/node-sqlite3-wasm.wasm",
     "dist/vendor/symbolic_bg.wasm"
   ],
   "license": "FSL-1.1-Apache-2.0",

package.json

@@ -135,6 +135,12 @@ async function bundleJs(): Promise<boolean> {
         "react-reconciler/*",
         // The DIF loader resolves this .wasm at runtime (dev only); never bundle it.
         "@sentry/symbolic/symbolic_bg.wasm",
+        // WASM SQLite fallback for Node.js < 22.15. The SEA binary always
+        // embeds a modern LTS Node.js (>= 22.15) and uses the native
+        // node:sqlite driver, so this fallback branch is dead code here.
+        // Externalizing it keeps the driver (and its ~1MB .wasm) out of the
+        // binary entirely — see src/lib/db/sqlite.ts resolveDriver().
+        "node-sqlite3-wasm",
       ],
       sourcemap: "linked",
       minify: true,

pnpm-lock.yaml

@@ -152,9 +152,17 @@ const sentrySourcemapPlugin: Plugin = {
 };
 
 // Always inject debug IDs (even without auth token); upload is gated inside the plugin
-/** Files that use _require() for lazy relative imports (circular dep breaking). */
+/**
+ * Files that use `_require()` for lazy imports. The `require-alias` plugin
+ * rewrites `_require(` → `require(` in these so esbuild resolves them at
+ * bundle time. `db/sqlite` is included so the WASM SQLite fallback
+ * (`node-sqlite3-wasm`) is actually inlined into the npm bundle — otherwise
+ * it stays a runtime `require()` that fails in a real install (the driver is
+ * a devDependency, not shipped). `node:sqlite` in the same file stays a
+ * builtin and is left external by esbuild regardless.
+ */
 const REQUIRE_ALIAS_FILTER =
-  /(?:db[\\/](?:index|schema)|list-command|telemetry)\.ts$/;
+  /(?:db[\\/](?:index|schema|sqlite)|list-command|telemetry)\.ts$/;
 const REQUIRE_ALIAS_RE = /\b_require\(/g;
 
 /** Transform _require() → require() so esbuild resolves lazy relative requires. */
@@ -194,7 +202,10 @@ const result = await build({
   // The library bundle must not suppress the host application's warnings.
   sourcemap: true,
   platform: "node",
-  target: "node24",
+  // Target Node.js 18 — the published package's floor (engines.node).
+  // Older Node.js uses the bundled WASM SQLite driver (node-sqlite3-wasm);
+  // 22.15+ uses the native node:sqlite. Downlevels newer syntax accordingly.
+  target: "node18",
   format: "cjs",
   outfile: "./dist/index.cjs",
   // Inject Bun polyfills and import.meta.url shim for CJS compatibility
@@ -218,10 +229,6 @@ const result = await build({
   // from trying to resolve these packages in the main bundle graph.
   external: [
     "node:*",
-    // bun:sqlite is referenced as a fallback in src/lib/db/sqlite.ts (never
-    // reached on Node 22+ where node:sqlite is available). Mark external so
-    // esbuild doesn't fail trying to resolve a Bun-only module.
-    "bun:sqlite",
     // The DIF loader resolves this .wasm at runtime (dev only); never bundle it.
     "@sentry/symbolic/symbolic_bg.wasm",
     "ink",
@@ -240,7 +247,7 @@ const result = await build({
 // Write the CLI bin wrapper (tiny — shebang + version check + dispatch).
 // Version floor must track `engines.node` in package.json.
 const BIN_WRAPPER = `#!/usr/bin/env node
-{let v=process.versions.node.split(".").map(Number);if(v[0]<22||(v[0]===22&&v[1]<15)){console.error("Error: sentry requires Node.js 22.15 or later (found "+process.version+").\\n\\nEither upgrade Node.js, or install the standalone binary instead:\\n  curl -fsSL https://cli.sentry.dev/install | bash\\n");process.exit(1)}}
+{let v=process.versions.node.split(".").map(Number);if(v[0]<18){console.error("Error: sentry requires Node.js 18 or later (found "+process.version+").\\n\\nEither upgrade Node.js, or install the standalone binary instead:\\n  curl -fsSL https://cli.sentry.dev/install | bash\\n");process.exit(1)}}
 {let e=process.emit;process.emit=function(n,...a){return n==="warning"?!1:e.apply(this,[n,...a])}}
 require('./index.cjs')._cli().catch(()=>{process.exitCode=1});
 `;
@@ -310,6 +317,18 @@ await copyFile(
 );
 console.log("  -> dist/vendor/symbolic_bg.wasm (DIF parser)");
 
+// Ship the WASM SQLite driver's .wasm next to the bundle. The driver JS
+// (node-sqlite3-wasm) is inlined into dist/index.cjs by esbuild, and its
+// Emscripten glue locates the .wasm via `__dirname + "/node-sqlite3-wasm.wasm"`.
+// Once bundled, `__dirname` is `dist/`, so the file must sit at
+// dist/node-sqlite3-wasm.wasm. Only loaded on Node.js < 22.15 (see
+// src/lib/db/sqlite.ts resolveDriver()); harmless dead weight on newer Node.
+await copyFile(
+  "./node_modules/node-sqlite3-wasm/dist/node-sqlite3-wasm.wasm",
+  "./dist/node-sqlite3-wasm.wasm"
+);
+console.log("  -> dist/node-sqlite3-wasm.wasm (WASM SQLite fallback)");
+
 // Calculate bundle size (only the main bundle, not source maps)
 const bundleOutput = result.metafile?.outputs["dist/index.cjs"];
 const bundleSize = bundleOutput?.bytes ?? 0;

script/build.ts

@@ -310,15 +310,41 @@ function extractNodeVersion(): string {
   return match[1];
 }
 
+/**
+ * Extract the Node.js minimum version for *development* from
+ * `devEngines.runtime.version`, falling back to `engines.node`.
+ *
+ * The published package supports a lower Node.js floor than local
+ * development: consumers on older Node.js use a bundled WASM SQLite driver,
+ * but contributors run the sources directly (tsx) against `node:sqlite`,
+ * which requires Node.js 22.15+. This keeps the two floors independent.
+ */
+function extractDevNodeVersion(): string {
+  const constraint: string | undefined =
+    // biome-ignore lint/suspicious/noExplicitAny: devEngines is not in the pkg type
+    (pkg as any).devEngines?.runtime?.version ?? pkg.engines?.node;
+  if (!constraint) {
+    throw new Error("Missing devEngines.runtime.version and engines.node");
+  }
+  const match = constraint.match(SEMVER_RE);
+  if (!match) {
+    throw new Error(
+      `Cannot extract dev Node.js version from "${constraint}". ` +
+        "Expected a semver-like version (e.g., >=22.15)"
+    );
+  }
+  return match[1];
+}
+
 /** Generate dev prerequisite line for README.md. */
 function generateDevPrereq(): string {
-  return `- [Node.js](https://nodejs.org) v${extractNodeVersion()}+ and [pnpm](https://pnpm.io) v${extractPnpmVersion()}+`;
+  return `- [Node.js](https://nodejs.org) v${extractDevNodeVersion()}+ and [pnpm](https://pnpm.io) v${extractPnpmVersion()}+`;
 }
 
 /** Generate dev prerequisite lines for contributing.md. */
 function generateDevPrereqContributing(): string {
   return [
-    `- [Node.js](https://nodejs.org) (v${extractNodeVersion()} or later)`,
+    `- [Node.js](https://nodejs.org) (v${extractDevNodeVersion()} or later)`,
     `- [pnpm](https://pnpm.io) (v${extractPnpmVersion()} or later)`,
   ].join("\n");
 }
@@ -331,7 +357,7 @@ function generateLibraryPrereq(): string {
 /** Generate dev prerequisite lines for DEVELOPMENT.md. */
 function generateDevPrereqDevelopment(): string {
   return [
-    `- [Node.js](https://nodejs.org/) v${extractNodeVersion()}+ installed`,
+    `- [Node.js](https://nodejs.org/) v${extractDevNodeVersion()}+ installed`,
     `- [pnpm](https://pnpm.io/) v${extractPnpmVersion()}+ installed`,
   ].join("\n");
 }