Node.js Client SDK v1.0: Now Stable

The PowerSync Node.js client SDK is now stable and @powersync/node@1.0.0 is available on npm. Stable means you can build on it confidently in production with the same support and SLA guarantees as our other stable SDKs.

Since the beta, the SDK moved to a new major version of the shared JavaScript API and received a long list of improvements and fixes. Here's what changed, and what to check when you upgrade.

What changed since the beta

The v2.0 JavaScript API

The biggest change is that @powersync/node moved to v2.0 of the PowerSync JavaScript SDKs. It's the main reason the SDK is stable now:

• A cleaner, more stable public API. @powersync/common used to expose the SDK's internals, so routine changes on our side could cause errors. It now exposes only public interfaces. (PR #1086)

• Simpler setup. Options are consolidated into fewer, clearer places: sync options on connect(), database options on the constructor, and a small logger interface instead of js-logger as a separate dependency.

• Smaller install. The SDK pulls in fewer packages, so installs are faster and there's less third-party code in your dependency tree. Additionally, WebSocket support now only loads if you opt in.

• Shared types across platforms. Write code like your backend connector once and reuse it in Node.js, web, and React Native, without platform-specific type annotations.

If you're upgrading from a beta version before v0.20.0, the v2.0 announcement walks through each breaking change. For most apps it's a few mechanical edits to how you construct the database, connect, and set up logging. One caveat: CommonJS builds have been removed, v2.0 is ESM only. The SDK can still be imported with require() as it contains no top-level await, but unsupported Node.js versions (Node 23 or older) might not work anymore.

Streaming attachments for large files

You can now sync large attachments, such as videos or recordings, without loading the whole file into memory. Previously the attachment queue held every file in memory while uploading or downloading it, which caused out-of-memory crashes for big files. Since v0.21.0 files stream directly between disk and the network, and saveFileFromUri() lets you queue a file that's already on disk without reading it in. Existing attachment setups keep working unchanged. (PR #1039, docs)

Attachment support is also part of @powersync/common now, so you no longer need the separate @powersync/attachments package (announcement).

Feature parity with our other SDKs

• Sync Streams. Subscribe to the data a process needs, when it needs it, instead of syncing everything upfront. Generally available since May 2026. (docs)

• Checkpoint requests, new in v1.0.0. Call requestCheckpoint() to catch up with the server on demand and know when your local database is up to date. Useful before a critical job, or when a background service needs to act on fresh data. Opt in with checkpointMode: 'requests' while the feature is in alpha. (announcement, docs, PR #1073)

• Rust sync client. Sync processing now runs inside the SQLite extension instead of in JavaScript. Large syncs finish faster and use less memory, and your process spends less CPU decoding sync data, so it stays responsive while data is coming in. (announcement, PR #828, PR #938)

• Encryption support. Encrypt the local database by swapping in a better-sqlite3 fork such as better-sqlite3-multiple-ciphers. See Encryption and Custom SQLite Drivers in the docs. (PR #690)

• Better observability. Tag connections with your own metadata via appMetadata on connect() so you can find them in the PowerSync Service sync logs, and sync errors now keep their full cause chain so they're easier to debug. (announcement, PR #1000)

• Sync reliability fixes. We fixed a series of race conditions reported by customers that could interrupt sync, from checksum errors to subscriptions lost during connect(). Sync should now recover cleanly from expired tokens and reconnects. (PR #960, PR #951, PR #1034, PR #1078)

Queries and data

• Incremental and differential watched queries. Watched queries only fire when their results actually change, and can tell you exactly which rows were added, removed, or updated. Less unnecessary work for whatever consumes the results. (announcement)

• Trigger-based diff tracking. For large result sets, where re-running the query on every change is too expensive, you can track changes with SQLite triggers instead. (announcement)

• Raw SQLite tables, now stable. Use your own SQLite tables, with full control over indexes and constraints, and PowerSync keeps them in sync. Setup is now simpler too: PowerSync infers the insert and delete statements from a table name. (PR #931, PR #855)

• Batched uploads. getCrudTransactions() iterates over pending transactions so you can upload them in batches instead of one at a time. (PR #693)

• TanStack DB integration. Query your synced data through TanStack DB collections, with live queries and optimistic mutations backed by the local SQLite database. (announcement, TanStack docs)

Upgrading

• On v0.20.0 or v0.21.0: v1.0.0 contains no breaking changes so you can simply upgrade the package. Checkpoint requests are opt-in.

• On an earlier beta version: follow the v2.0 upgrade steps first, then update to v1.0.0.

Get started

The Node.js SDK docs cover setup, and the example-node and example-electron-node demos show a complete setup, including encryption. The full version-by-version history is on the Node.js changelog page.

Reaching v1.0 is a major milestone. Thank you to everyone who ran the beta and reported feedback and bugs. If something doesn't work the way you expect, come chat with us on Discord or open an issue on GitHub.