Client-Side Setup - PowerSync

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:

Install the Client SDK (see below)
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.
Instantiate the PowerSync Database
- This instantiates the aforemention managed SQLite database.
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

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:

npx expo install @powersync/react-native

Required peer dependencies

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

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

Alternatively, you can install OP-SQLite with the PowerSync OP-SQLite package 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.
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 install @powersync/web

Required peer dependencies

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

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 {
            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

Swift

You can add the PowerSync Swift package to your project using either Package.swift or 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"
                )
            ]
        )
    ]
)

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

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

Swift

Node.js (Alpha)

Add the PowerSync Node NPM package to your project:

npm install @powersync/node

Required peer dependencies

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

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)

For desktop/server/binary use-cases and WPF, add the PowerSync.Common NuGet package to your project:

dotnet add package PowerSync.Common --prerelease

For desktop/server/binary use-cases and WPF, add the PowerSync.Common NuGet package to your project:

dotnet add package PowerSync.Common --prerelease

For MAUI apps, add both PowerSync.Common and PowerSync.Maui NuGet packages to your project:

dotnet add package PowerSync.Common --prerelease
dotnet add package PowerSync.Maui --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.

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

On this page

Overview
Installing the Client SDK
Next Steps

Overview

Install the Client SDK (see below)
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.
Instantiate the PowerSync Database
- This instantiates the aforemention managed SQLite database.
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

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:

npx expo install @powersync/react-native

Required peer dependencies

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

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

Alternatively, you can install OP-SQLite with the PowerSync OP-SQLite package 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.
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 install @powersync/web

Required peer dependencies

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

npm install @journeyapps/wa-sqlite

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

Swift

You can add the PowerSync Swift package to your project using either Package.swift or 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"
                )
            ]
        )
    ]
)

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

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

Swift

Node.js (Alpha)

Add the PowerSync Node NPM package to your project:

npm install @powersync/node

Required peer dependencies

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

npm install @powersync/better-sqlite3

Common installation issues

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)

For desktop/server/binary use-cases and WPF, add the PowerSync.Common NuGet package to your project:

dotnet add package PowerSync.Common --prerelease

For desktop/server/binary use-cases and WPF, add the PowerSync.Common NuGet package to your project:

dotnet add package PowerSync.Common --prerelease

For MAUI apps, add both PowerSync.Common and PowerSync.Maui NuGet packages to your project:

dotnet add package PowerSync.Common --prerelease
dotnet add package PowerSync.Maui --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.

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

On this page

Overview
Installing the Client SDK
Next Steps

​Overview

​Installing the Client SDK

​Next Steps

Resources

​Overview

​Installing the Client SDK

​Next Steps

Overview

Installing the Client SDK

Next Steps

Overview

Installing the Client SDK

Next Steps