gms1 · gms1 · Apr 21, 2026 · Apr 21, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -295,6 +295,14 @@ jobs:
           path: '*.tgz'
           retention-days: 7
 
+  test-package:
+    needs: [package]
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request') || (github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/'))
+    uses: ./.github/workflows/test-npm-package.yml
+    with:
+      target_run_id: ${{ github.run_id }}
+      node_version: '22'
+
   publish-npm:
     needs: [build, build-musl]
     if: startsWith(github.ref, 'refs/tags/')

diff --git a/.github/workflows/test-npm-package.yml b/.github/workflows/test-npm-package.yml
@@ -1,5 +1,16 @@
 name: Test npm package
 on:
+  workflow_call:
+    inputs:
+      target_run_id:
+        description: 'The Run ID of the upstream CI workflow'
+        required: true
+        type: string
+      node_version:
+        description: 'Node.js version to test with'
+        required: false
+        default: '20'
+        type: string
   workflow_dispatch:
     inputs:
       target_run_id:
@@ -35,15 +46,15 @@ jobs:
       - name: Download artifact from specific run
         uses: actions/download-artifact@v5
         with:
-          run-id: ${{ github.event.inputs.target_run_id }}
+          run-id: ${{ inputs.target_run_id }}
           github-token: ${{ secrets.GITHUB_TOKEN }}
           name: npm-package-tarball
           path: ./downloads
 
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: ${{ github.event.inputs.node_version || '20' }}
+          node-version: ${{ inputs.node_version || '20' }}
 
       - name: Install tarball and verify
         shell: bash
@@ -93,4 +104,62 @@ jobs:
               await db.close();
             }
             main().catch(err => { console.error(err); process.exit(1); });
-          "
+          "
+
+      - name: Smoke test - ESM default import
+        shell: bash
+        run: |
+          cd test-project
+          cat > test-esm.mjs << 'EOF'
+          import sqlite3 from '@homeofthings/sqlite3';
+          console.log('ESM: sqlite3 version:', sqlite3.VERSION);
+          const db = new sqlite3.Database(':memory:');
+          db.serialize(() => {
+            db.run('CREATE TABLE test (id INT, name TEXT)');
+            db.run("INSERT INTO test VALUES (1, 'hello')");
+            db.get('SELECT * FROM test', (err, row) => {
+              if (err) { console.error('Query failed:', err); process.exit(1); }
+              console.log('ESM default import result:', JSON.stringify(row));
+              db.close();
+            });
+          });
+          EOF
+          node test-esm.mjs
+
+      - name: Smoke test - ESM named imports
+        shell: bash
+        run: |
+          cd test-project
+          cat > test-named.mjs << 'EOF'
+          import { Database, OPEN_READWRITE, OPEN_CREATE } from '@homeofthings/sqlite3';
+          console.log('ESM named: OPEN_READWRITE=', OPEN_READWRITE);
+          const db = new Database(':memory:');
+          db.serialize(() => {
+            db.run('CREATE TABLE test (id INT, name TEXT)');
+            db.run("INSERT INTO test VALUES (2, 'world')");
+            db.get('SELECT * FROM test', (err, row) => {
+              if (err) { console.error('Query failed:', err); process.exit(1); }
+              console.log('ESM named import result:', JSON.stringify(row));
+              db.close();
+            });
+          });
+          EOF
+          node test-named.mjs
+
+      - name: Smoke test - ESM promise API
+        shell: bash
+        run: |
+          cd test-project
+          cat > test-promise.mjs << 'EOF'
+          import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
+          async function main() {
+            const db = await SqliteDatabase.open(':memory:');
+            await db.run('CREATE TABLE test (id INT, name TEXT)');
+            await db.run("INSERT INTO test VALUES (3, 'esm')");
+            const row = await db.get('SELECT * FROM test');
+            console.log('ESM promise API result:', JSON.stringify(row));
+            await db.close();
+          }
+          main().catch(err => { console.error(err); process.exit(1); });
+          EOF
+          node test-promise.mjs
diff --git a/README.md b/README.md
@@ -26,6 +26,7 @@ Asynchronous, non-blocking [SQLite3](https://sqlite.org/) bindings for [Node.js]
  - Written in modern C++
  - Is built using hardening flags
  - Promise-based API
+ - supports ESM and CJS
  - Bundles SQLite v3.53.0, or you can build using a local SQLite
 
 # Installing
@@ -108,6 +109,37 @@ async function main() {
 main().catch(console.error);
 ```
 
+## ESM and CJS Support
+
+This package supports both CommonJS (CJS) and ECMAScript Modules (ESM):
+
+### CJS (CommonJS)
+
+```js
+// Default import
+const sqlite3 = require('@homeofthings/sqlite3');
+
+// Destructured import
+const { Database, SqliteDatabase } = require('@homeofthings/sqlite3');
+
+// Promise subpath import
+const { SqliteDatabase } = require('@homeofthings/sqlite3/promise');
+```
+
+### ESM (ECMAScript Modules)
+
+```js
+// Default import
+import sqlite3 from '@homeofthings/sqlite3';
+
+// Named imports
+import { Database, OPEN_CREATE, SqliteDatabase } from '@homeofthings/sqlite3';
+
+// Promise subpath import
+import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
+```
+
+
 # Usage
 
 **Note:** the module must be [installed](#installing) before use.

diff --git a/docs/API.md b/docs/API.md
@@ -6,6 +6,7 @@ This document describes the API for `@homeofthings/sqlite3`, a Node.js binding f
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Module Systems (CJS & ESM)](#module-systems-cjs--esm)
 - [Callback API](#callback-api)
   - [Database Class](#database-class-callback)
   - [Statement Class](#statement-class-callback)
@@ -67,6 +68,40 @@ main().catch(console.error);
 
 ---
 
+## Module Systems (CJS & ESM)
+
+This package supports both CommonJS (CJS) and ECMAScript Modules (ESM) via conditional exports in `package.json`.
+
+### CJS (CommonJS) — Traditional
+
+```javascript
+// Default import
+const sqlite3 = require('@homeofthings/sqlite3');
+
+// Destructured import
+const { Database, SqliteDatabase, OPEN_CREATE } = require('@homeofthings/sqlite3');
+
+// Promise subpath import
+const { SqliteDatabase } = require('@homeofthings/sqlite3/promise');
+```
+
+### ESM (ECMAScript Modules) — Modern
+
+```javascript
+// Default import
+import sqlite3 from '@homeofthings/sqlite3';
+
+// Named imports
+import { Database, OPEN_CREATE, SqliteDatabase } from '@homeofthings/sqlite3';
+
+// Promise subpath import
+import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
+```
+
+> **Note:** The ESM wrappers use native CJS→ESM interop (`import` from `.js` files), so ESM imports work seamlessly alongside CJS requires. Both module systems share the same underlying native addon instance.
+
+---
+
 ## Callback API
 
 The traditional callback-based API is compatible with the original `node-sqlite3` API.
@@ -942,11 +977,20 @@ const sqlite3 = require('@homeofthings/sqlite3').verbose();
 
 ## TypeScript Support
 
-TypeScript definitions are included in the package:
+TypeScript definitions are included in the package. Both CJS and ESM import styles are supported:
 
 ```typescript
+// CJS style
+const sqlite3 = require('@homeofthings/sqlite3');
+const { Database, SqliteDatabase } = require('@homeofthings/sqlite3');
+
+// ESM style
+import sqlite3 from '@homeofthings/sqlite3';
 import { Database, Statement, Backup } from '@homeofthings/sqlite3';
 import { SqliteDatabase, SqliteStatement, SqliteBackup } from '@homeofthings/sqlite3';
+
+// Promise subpath
+import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
 ```
 
 ---

diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -6,7 +6,7 @@ export default [
         ignores: ['node_modules/', 'build/', 'prebuilds/', 'deps/'],
     },
     {
-        files: ['**/*.js'],
+        files: ['**/*.js', '**/*.mjs'],
         languageOptions: {
             ecmaVersion: 2020,
             sourceType: 'module',
@@ -24,7 +24,7 @@ export default [
         },
     },
     {
-        files: ['test/**/*.js'],
+        files: ['test/**/*.js', 'test/**/*.mjs'],
         languageOptions: {
             globals: {
                 ...globals.mocha,

diff --git a/lib/promise/database.js b/lib/promise/database.js
@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { Database } = require('../sqlite3.js');
+const { Database } = require('../sqlite3-callback.js');
 const { SqliteStatement } = require('./statement');
 const { SqliteBackup } = require('./backup');
 

diff --git a/lib/promise/index.d.ts b/lib/promise/index.d.ts
@@ -0,0 +1 @@
+export { SqliteDatabase, SqliteStatement, SqliteBackup, SqlRunResult } from '../sqlite3';
diff --git a/lib/promise/index.mjs b/lib/promise/index.mjs
@@ -0,0 +1,9 @@
+/**
+ * ESM wrapper for the Promise-based API of @homeofthings/sqlite3
+ *
+ * Usage:
+ *   import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
+ *   const db = await SqliteDatabase.open(':memory:');
+ */
+
+export { SqliteDatabase, SqliteStatement, SqliteBackup } from './index.js';
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		export { SqliteDatabase, SqliteStatement, SqliteBackup, SqlRunResult } from '../sqlite3';