# @powersync/node

> PowerSync Node.js SDK

Latest version **1.1.0** (published 2026-09-21) · Apache-2.0 license · 10.9K weekly downloads

## Install

```sh
npm install @powersync/node
pnpm add @powersync/node
yarn add @powersync/node
bun add @powersync/node
```

## Health

**Score 75/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: no types.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-09-21 |
| First published | 2025-03-13 |
| Weekly downloads | 10.9K |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 4.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 724 |
| Author | PowerSync |
| Maintainers | journeyapps-platform, journeyapps-admin |
| Keywords | data sync, offline-first, sqlite, real-time data stream, live data |

## Links

- npm: https://www.npmjs.com/package/@powersync/node
- Repository: https://github.com/powersync-ja/powersync-js
- Homepage: https://docs.powersync.com/
- Issues: https://github.com/powersync-ja/powersync-js/issues
- npm.io page: https://npm.io/package/@powersync/node

## Dependencies (4)

- [undici](https://npm.io/package/undici.md) ^7.11.0
- [comlink](https://npm.io/package/comlink.md) ^4.4.2
- [@powersync/common](https://npm.io/package/@powersync/common.md) 2.3.0
- [@powersync/shared-internals](https://npm.io/package/@powersync/shared-internals.md) 1.3.0

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads
- [medsci-skills](https://npm.io/package/medsci-skills.md) — 947 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-09-21
- 0.0.0-dev-20260917114458 (dev) — 2026-09-17
- 0.0.0-dev-20260917080037 — 2026-09-17
- 0.0.0-dev-20260917074240 — 2026-09-17
- 1.0.1 — 2026-09-10
- 1.0.0 — 2026-09-02
- 0.0.0-dev-20260827080125 — 2026-08-27
- 0.21.0 — 2026-08-13
- 0.20.2 — 2026-08-05
- 0.19.5 — 2026-08-04
- 0.20.1 — 2026-08-03
- 0.20.0 — 2026-07-21
- 0.19.4 — 2026-07-10
- 0.19.3 — 2026-07-07
- 0.0.0-dev-20260630144038 — 2026-06-30
- … 133 more at https://npm.io/package/@powersync/node/versions

## README

<p align="center">
  <a href="https://www.powersync.com" target="_blank"><img src="https://github.com/powersync-ja/.github/assets/7372448/d2538c43-c1a0-4c47-9a76-41462dba484f"/></a>
</p>

# PowerSync SDK for Node.js

_[PowerSync](https://www.powersync.com) keeps a client-side SQLite database in sync with your backend database. Changes appear across users and devices in real-time, user interactions feel instant and your app continues to work even when offline. Supports Postgres, MongoDB, MySQL, and SQL Server. Client SDKs are available for a wide range of environments including web, mobile, desktop, headless and embedded._

This package (`packages/node`) is the PowerSync SDK for Node.js clients. It is an extension of `packages/common`.
Using this package is not necessary for PowerSync on servers, see [our documentation](https://docs.powersync.com/installation/app-backend-setup) for more details on that.

See a summary of features [here](https://docs.powersync.com/client-sdk-references/node).

## Installation

### Install Package

```bash
npm install @powersync/node better-sqlite3
```

Both `@powersync/node` and the `better-sqlite3` packages have install scripts that need to run to compile
or download sqlite3 and PowerSync binaries.

### Common Installation Issues

The `better-sqlite` package requires native compilation, which depends on certain system tools. This compilation process is handled by `node-gyp` and may fail if required dependencies are missing or misconfigured.

#### Node-gyp Version Conflicts

`better-sqlite` depends on `node-gyp@^11`, but some project configurations may introduce multiple versions of `node-gyp`, potentially causing build issues.

#### Python Dependency Issues

`node-gyp` requires Python for compilation. If your project uses `node-gyp` below version `10` and your system has Python `3.12` or later, you may encounter the following error:

```python
ModuleNotFoundError: No module named 'distutils'
```

To resolve this, either:

- Upgrade `node-gyp` to version 10 or later.
- Install Python [setuptools](https://pypi.org/project/setuptools/), which includes `distutils`.

#### Package better-sqlite3 not found errors

This package does not import `better-sqlite3` statically (with unconditional `require()` or static `import` statements).
Instead, to allow users to use `node:sqlite` instead of that package, a dynamic `require()` / `import` expression is used.
This may prevent bundlers from detecting that `better-sqlite3` is used by this package.

To fix this, ensure you have a dependency on `better-sqlite3` (and, if you're using TypeScript, a dev-dependency on
`@types/better-sqlite3`).

In your project, create a `PowerSync.worker.ts` file with the following contents:

```TypeScript
import Database from 'better-sqlite3';

import { startPowerSyncWorker } from '@powersync/node/worker.js';

async function resolveBetterSqlite3() {
  return Database;
}

startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });
```

Finally, when you open the `PowerSyncDatabase`, instruct PowerSync to use your custom worker:

```TypeScript
const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'test.db',
    openWorker: (_, options) => {
      return new Worker(new URL('./PowerSync.worker.js', import.meta.url), options);
    }
  },
  logger
});
```

## Getting Started

The [Node.js SDK reference](https://docs.powersync.com/client-sdk-references/node)
contains everything you need to know to get started implementing PowerSync in your project.

## Examples

A simple example using `@powersync/node` is available in the [`demos/example-node/`](../demos/example-node) directory.

## Proxy Support

This SDK supports HTTP, HTTPS, and WebSocket proxies via environment variables.

### HTTP Connection Method

Internally we probe the http environment variables and apply it to fetch requests ([undici](https://www.npmjs.com/package/undici/v/5.6.0))

- Set the `HTTPS_PROXY` or `HTTP_PROXY` environment variable to automatically route HTTP requests through a proxy.

### WEB Socket Connection Method

Internally the [proxy-agent](https://www.npmjs.com/package/proxy-agent) dependency for WebSocket proxies, which has its own internal code for automatically picking up the appropriate environment variables:

- Set the `WS_PROXY` or `WSS_PROXY` environment variable to route the webocket connections through a proxy.

## Encryption

This package can be used with the [`better-sqlite3-multiple-ciphers`](https://www.npmjs.com/package/better-sqlite3-multiple-ciphers) fork of `better-sqlite3` for encryption.

This requires a custom worker loading the forked package:

```TypeScript
// encryption.worker.ts
import Database from 'better-sqlite3-multiple-ciphers';

import { startPowerSyncWorker } from '@powersync/node/worker.js';

async function resolveBetterSqlite3() {
  return Database;
}

startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });
```

Then, when opening the database, use that custom worker:

```TypeScript
const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'test.db',
    openWorker: (_, options) => {
      return new Worker(new URL('./PowerSync.worker.js', import.meta.url), options);
    },
    initializeConnection: async (db) => {
      if (encryptionKey.length) {
        const escapedKey = encryptionKey.replaceAll("'", "''");
        await db.execute(`PRAGMA key = '${escapedKey}'`);
      }

      // Make sure the database is readable, this fails early if the key is wrong.
      await db.execute('PRAGMA user_version');
    }
  },
  logger
});
```

## Found a bug or need help?

- Join our [Discord server](https://discord.gg/powersync) where you can browse topics from our community, ask questions, share feedback, or just say hello :)
- Please open a [GitHub issue](https://github.com/powersync-ja/powersync-js/issues) when you come across a bug.
- Have feedback or an idea? [Submit an idea](https://roadmap.powersync.com/tabs/5-roadmap/submit-idea) via our public roadmap or [schedule a chat](https://calendly.com/powersync-product/powersync-chat) with someone from our product team.

## Thanks

The PowerSync Node.js SDK relies on the work contributors and maintainers have put into the upstream better-sqlite3 package.
In particular, we'd like to thank [@spinda](https://github.com/spinda) for contributing support for update, commit and rollback hooks!

---
_Source: https://npm.io/package/@powersync/node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._