Client-Side Setup

Include the PowerSync Client SDK in your project

Overview

If you’re following the Implementation Outline: after configuring your database, connecting your PowerSync instance to it, and defining basic Sync Rules, the next step 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 Client SDK (see below)

2. Define your Client-Side Schema

   • The PowerSync Client SDKs expose a managed SQLite database that your app can read from and write to. The client-side schema refers to the schema for that SQLite database.

3. Instantiate the PowerSync Database

   • This instantiates the aforemention managed SQLite database.

4. Integrate with your Backend [Optional]

   • This allows write operations on the client-side SQLite database to be uploaded to your backend and applied to your backend database.

   • Integrating with your backend is also part of authentication integration. For initial development and testing, you can use Development Tokens, and then implement proper authentication integration at a later time.

Installing the Client SDK

PowerSync offers a variety of client SDKs. Please see the steps based on your app language and 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

Add the PowerSync React Native NPM package to your project:

npm

npx expo install @powersync/react-native

Install peer dependencies

PowerSync requires a SQLite database adapter.

Using Expo Go? Our native database adapters listed below (OP-SQLite and React Native Quick SQLite) are not compatible with Expo Go’s sandbox environment. To run PowerSync with Expo Go install our JavaScript-based adapter @powersync/adapter-sql-js instead. See details here.

Choose between:

OP-SQLite (Recommended)

PowerSync OP-SQLite offers:

• Built-in encryption support via SQLCipher
• Smoother transition to React Native’s New Architecture

npm

npx expo install @powersync/op-sqlite @op-engineering/op-sqlite

React Native Quick SQLite

The @journeyapps/react-native-quick-sqlite package is the original database adapter for React Native and therefore more battle-tested in production environments.

npm

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

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.

• When using the OP-SQLite package, we recommend adding this metro config to avoid build issues.

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

npm install @powersync/web

Required peer dependencies

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

npm

npm install @journeyapps/wa-sqlite

By default, this SDK connects to a PowerSync instance via WebSocket (from @powersync/web@1.6.0) or HTTP streaming (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 {
            implementation("com.powersync:core:$powersyncVersion")
            // If you want to use the Supabase Connector, also add the following:
            implementation("com.powersync:connector-supabase:$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

Swift

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

Package.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"
                )
            ]
        )
    ]
)

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

Swift

Node.js (Beta)

Add the PowerSync Node NPM package to your project:

npm

npm install @powersync/node

Required peer dependencies

This SDK requires @powersync/better-sqlite3 as a peer dependency:

npm

npm install @powersync/better-sqlite3

Common installation issues

The @powersync/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 (Alpha)

Common

For desktop/server/binary use-cases and WPF, add the PowerSync.Common 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 Client-Side Schema

2. Instantiate the 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.