Client-Side Setup

Include the PowerSync Client SDK in your project

The next step after configuring your database and connecting it to your PowerSync instance, is to include the appropriate PowerSync Client SDK package in your app project. On a high level, this involves the following steps:

1. Install the SDK (see below)

2. Define your Schema

3. Instantiate Local PowerSync Database

4. Integrate with your Backend [Optional]

   1. Download data from your database

   2. Write mutations to your backend

PowerSync currently supports apps built in Flutter, React Native & Expo, JavaScript Web, Node.js (alpha), Kotlin Multiplatform (beta), Swift (beta), and .NET (alpha).

Please see the steps based on your app framework:

Flutter

Add the PowerSync pub.dev package to your project:

flutter pub add powersync

See the full SDK reference for further details and getting started instructions:

Flutter

React Native & Expo

PowerSync is not compatible with Expo Go. PowerSync uses a native plugin and is therefore only compatible with Expo Dev Builds.

Add the PowerSync React Native NPM package to your project:

• npm
• yarn
• pnpm

npx expo install @powersync/react-native

npx expo install @powersync/react-native

yarn expo add @powersync/react-native

pnpm expo install @powersync/react-native

Required peer dependencies

This SDK requires @journeyapps/react-native-quick-sqlite as a peer dependency. Install it as follows:

• npm
• yarn
• pnpm

npx expo install @journeyapps/react-native-quick-sqlite

npx expo install @journeyapps/react-native-quick-sqlite

yarn expo add @journeyapps/react-native-quick-sqlite

pnpm expo install @journeyapps/react-native-quick-sqlite

Alternatively, you can install OP-SQLite from the PowerSync OP-SQLite package (currently in alpha) which offers built-in encryption support via SQLCipher and a smoother transition to React Native’s New Architecture.

Polyfills and additional notes:

• For async iterator support with watched queries additional polyfills are required. See the Babel plugins section in the README.

• By default, this SDK connects to a PowerSync instance via WebSocket (from @powersync/react-native@1.11.0) or HTTP Streaming (before @powersync/react-native@1.11.0). See Developer Notes for more details on connection methods and platform-specific requirements.

See the full SDK reference for further details and getting started instructions:

React Native & Expo

JavaScript Web

Add the PowerSync Web NPM package to your project:

• npm
• yarn
• pnpm

npm install @powersync/web

npm install @powersync/web

yarn add @powersync/web

pnpm install @powersync/web

Required peer dependencies

This SDK currently requires @journeyapps/wa-sqlite as a peer dependency. Install it in your app with:

• npm
• yarn
• pnpm

npm install @journeyapps/wa-sqlite

npm install @journeyapps/wa-sqlite

yarn add @journeyapps/wa-sqlite

pnpm install @journeyapps/wa-sqlite

By default, this SDK connects to a PowerSync instance via WebSocket (from @powersync/web@1.6.0) or HTTP stream (before @powersync/web@1.6.0). See Developer Notes for more details on connection methods.

See the full SDK reference for further details and getting started instructions:

JavaScript Web

Kotlin Multiplatform

Add the PowerSync SDK to your project by adding the following to your build.gradle.kts file:

kotlin {
    //...
    sourceSets {
        commonMain.dependencies {
            api("com.powersync:core:$powersyncVersion")
            // If you want to use the Supabase Connector, also add the following:
            implementation("com.powersync:connectors:$powersyncVersion")
        }
        //...
    }
}

Cocoapods configuration (recommended for iOS)

Add the following to the cocoapods config in your build.gradle.kts:

cocoapods {
    //...
    pod("powersync-sqlite-core") {
        linkOnly = true
    }

    framework {
        isStatic = true
        export("com.powersync:core")
    }
    //...
}

The linkOnly = true attribute and isStatic = true framework setting ensure that the powersync-sqlite-core binaries are statically linked.

See the full SDK reference for further details and getting started instructions:

Kotlin Multiplatform (Beta)

Swift

You can add the PowerSync Swift package to your project using either Package.swift or Xcode:

• Package.swift
• Xcode

let package = Package(
    //...
    dependencies: [
        //...
        .package(
            url: "https://github.com/powersync-ja/powersync-swift",
            exact: "<version>"
        ),
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: [
                .product(
                    name: "PowerSync",
                    package: "powersync-swift"
                )
            ]
        )
    ]
)

let package = Package(
    //...
    dependencies: [
        //...
        .package(
            url: "https://github.com/powersync-ja/powersync-swift",
            exact: "<version>"
        ),
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: [
                .product(
                    name: "PowerSync",
                    package: "powersync-swift"
                )
            ]
        )
    ]
)

1. Follow this guide to add a package to your project.
2. Use https://github.com/powersync-ja/powersync-swift.git as the URL
3. Include the exact version (e.g., 1.0.0-Beta.x)

See the full SDK reference for further details and getting started instructions:

Swift (Beta)

Node.js

Add the PowerSync Node NPM package to your project:

• npm
• yarn
• pnpm

npm install @powersync/node

npm install @powersync/node

yarn add @powersync/node

pnpm install @powersync/node

Required peer dependencies

This SDK requires better-sqlite3 as a peer dependency:

• npm
• yarn
• pnpm

npm install better-sqlite3

npm install better-sqlite3

yarn add better-sqlite3

pnpm install better-sqlite3

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.

Refer to the PowerSync Node package README for more details.

See the full SDK reference for further details and getting started instructions:

Node.js (client)

.NET

Add the PowerSync .NET NuGet package to your project:

dotnet add package PowerSync.Common --prerelease

Add --prerelease while this package is in alpha.

See the full SDK reference for further details and getting started instructions:

.NET (Alpha)

Next Steps

For an overview of the client-side steps required to set up PowerSync in your app, continue reading the next sections.

1. Define your Schema

2. Instantiate PowerSync Database

3. Integrate with your Backend

For a walkthrough with example implementations for your platform, see the Getting Started section of the corresponding SDK reference linked above.