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.
PowerSync is tailored for client-side applications — there isn’t much benefit to using SSR with PowerSync. Some frameworks like Next.js push towards enabling SSR by default, which means code is evaluated in a Node.js runtime. The PowerSync Web SDK requires browser APIs which are not available in Node.js. For ergonomics, the SDK performs no-ops if used in Node.js (rather than throwing errors), but you should not expect any data from PowerSync during server-side rendering. If you are using SSR in your application, we recommend explicitly isolating PowerSync to client-side code.
Setup
Next.js Project Setup
Let’s start by bootstrapping a new Next.js application using create-next-app.
npx create-next-app@latest my-powersync-app
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`? Yes
Would you like to customize the import alias (`@/*` by default)? Yes
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.
npm install @powersync/web @journeyapps/wa-sqlite @powersync/react
Copy Worker Assets
When using Turbopack, you need to copy the PowerSync worker files to your public directory. Add a postinstall script to your package.json:
{
"scripts": {
"postinstall": "powersync-web copy-assets -o public"
}
}
public/@powersync/, which are required since Turbopack doesn’t support dynamic imports of workers yet.
Add public/@powersync/* to your .gitignore file since these are generated assets.
Next.js Config Setup
For Next.js 16+ with Turbopack, the configuration is minimal:
module.exports = {
images: {
disableStaticImages: true
},
turbopack: {}
};
pnpm dev to start the development server and check that everything compiles correctly, before moving onto the next section.
Webpack configuration (legacy)
If you’re using an older version of Next.js (before 16) or prefer to use Webpack, use this configuration instead:
module.exports = {
webpack: (config: any, { isServer }: any) => {
config.experiments = {
...config.experiments,
asyncWebAssembly: true,
topLevelAwait: true,
};
if (!isServer) {
config.module.rules.push({
test: /\.wasm$/,
type: "asset/resource",
});
}
return config;
}
}
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'];
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();
}
}
}
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 backend source 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, createBaseLogger, LogLevel } from '@powersync/web';
import React, { Suspense } from 'react';
const logger = createBaseLogger();
logger.useDefaults();
logger.setLevel(LogLevel.DEBUG);
const factory = new WASQLiteOpenFactory({
dbFilename: 'powersync.db',
// Use the pre-bundled worker from public/@powersync/
// This is required since Turbopack doesn't support dynamic imports of workers yet
worker: '/@powersync/worker/WASQLiteDB.umd.js'
});
export const db = new PowerSyncDatabase({
database: factory,
schema: AppSchema,
flags: {
disableSSRWarning: true
},
sync: {
// Use the pre-bundled sync worker from public/@powersync/
worker: '/@powersync/worker/SharedSyncImplementation.umd.js'
}
});
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;
SystemProvider is responsible for initializing the PowerSyncDatabase. The worker paths point to the pre-bundled workers copied to the public directory by the powersync-web copy-assets command.
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.
Update layout.tsx
In our main layout.tsx we’ll update the RootLayout function to use the SystemProvider.
'use client';
import { SystemProvider } from '@/app/components/providers/SystemProvider';
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
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`}>
<SystemProvider>{children}</SystemProvider>
</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.
'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]);
uploadData in the BackendConnector class.
