Next.js + PowerSync

A guide for creating a new Next.js application with PowerSync for offline/local first functionality

Introduction

In this tutorial, we’ll explore how to enhance a Next.js application with offline-first capabilities using PowerSync. In the following sections, we’ll walk through the process of integrating PowerSync into a Next.js application, setting up local-first storage, and handling synchronization efficiently.

At present PowerSync will not work with SSR enabled with Next.js and in this guide we disable SSR across the entire app. However, it is possible to have other pages, which do not require authentication for example, to still be rendered server-side. This can be done by only using the DynamicSystemProvider (covered further down in the guide) for specific pages. This means you can still have full SSR on other page which do not require PowerSync.

Setup

Next.js Project Setup

Let’s start by bootstrapping a new Next.js application using create-next-app.

pnpm dlx create-next-app@latest <project_name>

When running this command you’ll be presented with a few options. The PowerSync suggested selection for the setup options Next.js offers are:

Would you like to use TypeScript?  Yes
Would you like to use ESLint?  Yes
Would you like to use Tailwind CSS?  Yes
Would you like your code inside a `src/` directory?  Yes
Would you like to use App Router? (recommended)   Yes
Would you like to use Turbopack for `next dev`?  No
Would you like to customize the import alias (`@/*` by default)?  Yes

Do not use Turbopack when setting up a new Next.js project as we’ll be updating the next.config.ts to use Webpack. This is done because we need to enable:

1. asyncWebAssembly
2. topLevelWait

Install PowerSync Dependencies

Using PowerSync in a Next.js application will require the use of the PowerSync Web SDK and it’s peer dependencies.

In addition to this we’ll also install @powersync/react, which provides several hooks and providers for easier integration.

pnpm install @powersync/web @journeyapps/wa-sqlite @powersync/react js-logger

This SDK currently requires @journeyapps/wa-sqlite as a peer dependency.

Installing js-logger is very useful for debugging.

Next.js Config Setup

In order for PowerSync to work with the Next.js we’ll need to modify the default next.config.ts to support PowerSync.

next.config.ts

module.exports = {
    experimental: {
        turbo: false,
    },
    webpack: (config: any, isServer: any) => {
        config.experiments = {
            ...config.experiments,
            asyncWebAssembly: true, // Enable WebAssembly in Webpack
            topLevelAwait: true,
        };

        // For Web Workers, ensure proper file handling
        if (!isServer) {
            config.module.rules.push({
                test: /\.wasm$/,
                type: "asset/resource", // Adds WebAssembly files to the static assets
            });
        }

        return config;
    }
}

Some important notes here, we have to enable asyncWebAssemply in Webpack, topLevelAwait is required and for Web Workers, ensure proper file handling. It’s also important to add web assembly files to static assets for the site. We will not be using SSR because PowerSync does not support it.

Run pnpm dev to start the development server and check that everything compiles correctly, before moving onto the next section.

Configure a PowerSync Instance

Now that we’ve got our project setup, let’s create a new PowerSync Cloud instance and connect our client to it. For the purposes of this demo, we’ll be using Supabase as the source backend database that PowerSync will connect to.

To set up a new PowerSync instance, follow the steps covered in the Installation - Database Connection docs page.

Configure PowerSync in your project

Add core PowerSync files

Start by adding a new directory in ./src/lib named powersync.

AppSchema

Create a new file called AppSchema.ts in the newly created powersync directory and add your App Schema to the file. Here is an example of this.

lib/powersync/AppSchema.ts

import { column, Schema, Table } from '@powersync/web';

const lists = new Table({
  created_at: column.text,
  name: column.text,
  owner_id: column.text
});

const todos = new Table(
  {
    list_id: column.text,
    created_at: column.text,
    completed_at: column.text,
    description: column.text,
    created_by: column.text,
    completed_by: column.text,
    completed: column.integer
  },
  { indexes: { list: ['list_id'] } }
);

export const AppSchema = new Schema({
  todos,
  lists
});

// For types
export type Database = (typeof AppSchema)['types'];
export type TodoRecord = Database['todos'];
// OR:
// export type Todo = RowType<typeof todos>;
export type ListRecord = Database['lists'];

This defines the local SQLite database schema and PowerSync will hydrate the tables once the SDK connects to the PowerSync instance.

BackendConnector

Create a new file called BackendConnector.ts in the powersync directory and add the following to the file.

lib/powersync/BackendConnector.ts

import { AbstractPowerSyncDatabase, PowerSyncBackendConnector, UpdateType } from '@powersync/web';

export class BackendConnector implements PowerSyncBackendConnector {
    private powersyncUrl: string | undefined;
    private powersyncToken: string | undefined;

    constructor() {
        this.powersyncUrl = process.env.NEXT_PUBLIC_POWERSYNC_URL;
        // This token is for development only.
        // For production applications, integrate with an auth provider or custom auth.
        this.powersyncToken = process.env.NEXT_PUBLIC_POWERSYNC_TOKEN;
    }

    async fetchCredentials() {
        // TODO: Use an authentication service or custom implementation here.
        if (this.powersyncToken == null || this.powersyncUrl == null) {
            return null;
        }

        return {
            endpoint: this.powersyncUrl,
            token: this.powersyncToken
        };
    }

    async uploadData(database: AbstractPowerSyncDatabase): Promise<void> {
        const transaction = await database.getNextCrudTransaction();

        if (!transaction) {
            return;
        }

        try {
            for (const op of transaction.crud) {
              // The data that needs to be changed in the remote db
              const record = { ...op.opData, id: op.id };
              switch (op.op) {
                case UpdateType.PUT:
                  // TODO: Instruct your backend API to CREATE a record
                  break;
                case UpdateType.PATCH:
                  // TODO: Instruct your backend API to PATCH a record
                  break;
                case UpdateType.DELETE:
                  //TODO: Instruct your backend API to DELETE a record
                  break;
              }
            }
            await transaction.complete();
        } catch (error: any) {
            console.error(`Data upload error - discarding`, error);
            await transaction.complete();
        }
    }
}

There are two core functions to this file:

• fetchCredentials() - Used to return a JWT token to the PowerSync service for authentication.
• uploadData() - Used to upload changes captured in the local SQLite database that need to be sent to the source backend database, in this case Supabase. We’ll get back to this further down.

You’ll notice that we need to add a .env file to our project which will contain two variables:

• NEXT_PUBLIC_POWERSYNC_URL - This is the PowerSync instance url. You can grab this from the PowerSync Cloud dashboard.
• NEXT_PUBLIC_POWERSYNC_TOKEN - For development purposes we’ll be using a development token. To generate one, please follow the steps outlined in Development Token from our installation docs.

Create Providers

Create a new directory in ./src/app/components named providers

SystemProvider

Add a new file in the newly created providers directory called SystemProvider.tsx.

components/providers/SystemProvider.tsx

'use client';

import { AppSchema } from '@/lib/powersync/AppSchema';
import { BackendConnector } from '@/lib/powersync/BackendConnector';
import { PowerSyncContext } from '@powersync/react';
import { PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS } from '@powersync/web';
import Logger from 'js-logger';
import React, { Suspense } from 'react';

// eslint-disable-next-line react-hooks/rules-of-hooks
Logger.useDefaults();
Logger.setLevel(Logger.DEBUG);

export const db = new PowerSyncDatabase({
    schema: AppSchema,
    database: new WASQLiteOpenFactory({
        dbFilename: 'exampleVFS.db',
        vfs: WASQLiteVFS.OPFSCoopSyncVFS,
        flags: {
            enableMultiTabs: typeof SharedWorker !== 'undefined',
            ssrMode: false
        }
    }),
    flags: {
        enableMultiTabs: typeof SharedWorker !== 'undefined',
    }
});

const connector = new BackendConnector();
db.connect(connector);

export const SystemProvider = ({ children }: { children: React.ReactNode }) => {

    return (
        <Suspense>
            <PowerSyncContext.Provider value={db}>{children}</PowerSyncContext.Provider>
        </Suspense>
    );
};

export default SystemProvider;

The SystemProvider will be responsible for initializing the PowerSyncDatabase. Here we supply a few arguments, such as the AppSchema we defined earlier along with very important properties such as ssrMode: false. PowerSync will not work when rendered server side, so we need to explicitly disable SSR.

We also instantiate our BackendConnector and pass an instance of that to db.connect(). This will connect to the PowerSync instance, validate the token supplied in the fetchCredentials function and then start syncing with the PowerSync service.

DynamicSystemProvider.tsx

Add a new file in the newly created providers directory called DynamicSystemProvider.tsx.

components/providers/DynamicSystemProvider.tsx

'use client';

import dynamic from 'next/dynamic';

export const DynamicSystemProvider = dynamic(() => import('./SystemProvider'), {
    ssr: false
});

We can only use PowerSync in client side rendering, so here we’re setting ssr:false

Update layout.tsx

In our main layout.tsx we’ll update the RootLayout function to use the DynamicSystemProvider created in the last step.

app/layout.tsx

import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import { DynamicSystemProvider } from '@/app/components/providers/DynamicSystemProvider';

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
        <DynamicSystemProvider>{children}</DynamicSystemProvider>
      </body>
    </html>
  );
}

Use PowerSync

Reading Data

In our page.tsx we can now use the useQuery hook or other PowerSync functions to read data from the SQLite database and render the results in our application.

app/page.tsx

'use client';

import { useState, useEffect } from 'react';
import { useQuery, useStatus, usePowerSync } from '@powersync/react';

export default function Page() {
    // Hook
    const powersync = usePowerSync();

    // Get database status information e.g. downloading, uploading and lastSycned dates
    const status = useStatus();

    // Example 1: Reactive Query
    const { data: lists } = useQuery("SELECT * FROM lists");

    // Example 2: Standard query
    const [lists, setLists] = useState([]);
    useEffect(() => {
        powersync.getAll('SELECT * from lists').then(setLists)
    }, []);

    return (
    <ul>
      {lists.map(list => <li key={list.id}>{list.name}</li>)}
    </ul>
  )
}

Writing Data

Using the execute function we can also write data into our local SQLite database.

await powersync.execute("INSERT INTO lists (id, created_at, name, owner_id) VALUES (?, ?, ?, ?)", [uuid(), new Date(), "Test", user_id]);

Changes made against the local data will be stored in the upload queue and will be processed by the uploadData in the BackendConnector class.