index

PowerSync Nuxt

PowerSync for Nuxt: offline-first sync with native Nuxt integration

[!NOTE] The Nuxt package is currently in an alpha state, intended strictly for testing. Expect breaking changes and instability as development continues.

Do not rely on this package for production use.

PowerSync Nuxt module integrated with the Nuxt Devtools.

Changelog

Features

Real-time offline-first sync — PowerSync keeps a local SQLite database in sync with your backend (Postgres, MongoDB, MySQL, or SQL Server). Your app reads from local SQLite and works offline; changes sync automatically when the connection is restored.
Auto-imported composables — usePowerSync(), useQuery(), and usePowerSyncKysely() are available in every component without explicit imports.
Built-in diagnostics — View connection and sync status, inspect sync buckets and config, and tail real-time logs via the PowerSync Inspector — accessible at /__powersync-inspector or through Nuxt Devtools.
Data inspection — Browse your local SQLite database in the browser without external tools — useful for verifying what data has synced and debugging data issues during development.
Kysely support — Opt-in type-safe queries via @powersync/kysely-driver, enabled with kysely: true in your PowerSync config.

Installation

This module re-exports all @powersync/vue composables. With npm (v7+), installing @powersync/nuxt is enough; with pnpm, install peer dependencies explicitly.

# Using npm
npm install @powersync/nuxt

# Using pnpm (peer deps are not auto-installed)
pnpm add @powersync/nuxt @powersync/vue @powersync/web

[!NOTE] This module works with Nuxt 4 and should work with Nuxt 3 but has not been tested. Support for Nuxt 2 is not guaranteed or planned.

Quick Start

For a complete working app, see the Nuxt + Supabase Todo List demo. To set up from scratch:

Add @powersync/nuxt to the modules section of nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@powersync/nuxt'],
  vite: {
    optimizeDeps: {
      exclude: ['@powersync/web']
    },
    worker: {
      format: 'es'
    }
  }
});

[!WARNING]
If you are using Tailwind in your project see Known Issues section

Create a PowerSync plugin (e.g., plugins/powersync.client.ts):

import { NuxtPowerSyncDatabase } from '@powersync/nuxt';
import { createPowerSyncPlugin } from '@powersync/nuxt';
import { AppSchema } from '~/powersync/AppSchema';
import { PowerSyncConnector } from '~/powersync/PowerSyncConnector';

export default defineNuxtPlugin({
  async setup(nuxtApp) {
    const db = new NuxtPowerSyncDatabase({
      database: {
        dbFilename: 'your-db-filename.sqlite'
      },
      schema: AppSchema
    });

    const connector = new PowerSyncConnector();

    await db.init();
    await db.connect(connector);

    const plugin = createPowerSyncPlugin({ database: db });
    nuxtApp.vueApp.use(plugin);
  }
});

At this point, you're all set to use the module composables. The module automatically exposes all @powersync/vue composables, so you can use them directly:

usePowerSync() - Access the PowerSync database instance
useQuery() - Query the database reactively
And more... (see API Reference)

Setting up PowerSync

This guide will walk you through the steps to set up PowerSync in your Nuxt project.

Create your Schema

Create a file called AppSchema.ts and add your schema to it.

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'];
export type ListRecord = Database['lists'];

Tip: Learn more about how to create your schema here.

Create your Connector

Create a file called PowerSyncConnector.ts and add your connector to it.

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

export class PowerSyncConnector implements PowerSyncBackendConnector {
  async fetchCredentials() {
    // Implement fetchCredentials to obtain a JWT from your authentication service.
    // See https://docs.powersync.com/installation/authentication-setup
    // If you're using Supabase or Firebase, you can re-use the JWT from those clients, see
    // - https://docs.powersync.com/installation/authentication-setup/supabase-auth
    // - https://docs.powersync.com/installation/authentication-setup/firebase-auth
    return {
      endpoint: '[Your PowerSync instance URL or self-hosted endpoint]',
      // Use a development token (see Authentication Setup https://docs.powersync.com/installation/authentication-setup/development-tokens) to get up and running quickly
      token: 'An authentication token'
    };
  }

  async uploadData(db: any) {
    // Implement uploadData to send local changes to your backend service.
    // You can omit this method if you only want to sync data from the database to the client

    // See example implementation here: https://docs.powersync.com/client-sdk-references/javascript-web#3-integrate-with-your-backend
    // see demos here: https://github.com/powersync-ja/powersync-js/tree/main/demos
    return;
  }
}

Tip: Learn more about how to create your connector here.

Create your PowerSync Plugin

Finally, putting everything together, create a plugin called powersync.client.ts to setup PowerSync.

import { createPowerSyncPlugin } from '@powersync/nuxt';
import { NuxtPowerSyncDatabase } from '@powersync/nuxt';
import { AppSchema } from '~/powersync/AppSchema';
import { PowerSyncConnector } from '~/powersync/PowerSyncConnector';

export default defineNuxtPlugin({
  async setup(nuxtApp) {
    const db = new NuxtPowerSyncDatabase({
      database: {
        dbFilename: 'a-db-name.sqlite'
      },
      schema: AppSchema
    });

    const connector = new PowerSyncConnector();

    await db.init();
    await db.connect(connector);

    const plugin = createPowerSyncPlugin({ database: db });

    nuxtApp.vueApp.use(plugin);
  }
});

Kysely ORM (Optional)

You can use Kysely as your ORM to interact with the database. The module optionally provides a usePowerSyncKysely() composable. To keep the bundle small, you must install the driver yourself and enable it in config.

Install the driver:

pnpm add @powersync/kysely-driver

In your existing nuxt.config.ts, set:

export default defineNuxtConfig({
  modules: ['@powersync/nuxt'],
  powersync: {
    kysely: true // <- opt-in
  },
  vite: {
    optimizeDeps: {
      exclude: ['@powersync/web']
    },
    worker: {
      format: 'es'
    }
  }
});

When enabled, the module exposes usePowerSyncKysely. Use your schema’s Database type to get proper typings:

import { usePowerSyncKysely } from '@powersync/nuxt';
import { type Database } from '../powersync/AppSchema';

// In your component or composable
const db = usePowerSyncKysely<Database>();

// Use the db object to interact with the database
const users = await db.selectFrom('users').selectAll().execute();

Enabling Diagnostics

To enable the PowerSync Inspector with diagnostics capabilities:

Enable diagnostics in your config:

export default defineNuxtConfig({
  modules: ['@powersync/nuxt'],
  powersync: {
    useDiagnostics: true // <- Add this
  },
  vite: {
    optimizeDeps: {
      exclude: ['@powersync/web']
    },
    worker: {
      format: 'es'
    }
  }
});

When useDiagnostics: true is set, NuxtPowerSyncDatabase automatically:

Extend your schema with diagnostics schema
Sets up diagnostics recording
Stores the connector internally (accessible via diagnostics)
Configures logging for diagnostics

Accessing PowerSync Inspector:

Once diagnostics are enabled, you can access the PowerSync Inspector:

Via Nuxt Devtools: Open Devtools and look for the PowerSync tab
Direct URL: http://localhost:3000/__powersync-inspector

PowerSync Inspector

PowerSync Inspector is a tool that helps inspect and diagnose the state of your PowerSync client directly from your app in real-time.

Setup

To setup the PowerSync inspector, you need to follow the steps in the Enabling Diagnostics section.

Once setup, the inspector can be accessed on the http://localhost:3000/__powersync-inspector route or via the Nuxt Devtools.

Features

Sync Status

The Sync Status tab provides a real-time view of the sync status of your PowerSync client, including:

Connection status
Sync progress
Upload queue statistics
Error monitoring

Data Inspector

Browse and inspect your local database tables and data with powerful filtering and search capabilities.

Config Inspector

View and inspect your PowerSync configuration, connection options, and schema information.

Logs

Real-time logging of PowerSync operations with syntax highlighting and search functionality.

Nuxt Devtools

The inspector is also available in the Nuxt Devtools as a tab, providing seamless integration with your development workflow.

Known Issues

PowerSync Inspector relies on unocss as a transitive dependency. It might clash with your existing setup, for example if you use Tailwind CSS.

To fix this, you can add the following to your nuxt.config.ts:

export default defineNuxtConfig({
  unocss: {
    autoImport: false
  }
});

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Run Vitest
pnpm run test
pnpm run test:watch

Local Testing

If the playground is not enough for you, you can test the module locally by cloning this repo and pointing the nuxt app you want to test to the local module.

Don't forget to add a watcher for the module for hot reloading.

Example (in your nuxt app):

import { defineNuxtConfig } from 'nuxt/config';

export default defineNuxtConfig({
  modules: ['../../my-location/@powersync/nuxt/src/*'],
  watch: ['../../my-location/@powersync/nuxt/src/*']
});

PowerSync Nuxt

Features​

Installation​

Quick Start​

Setting up PowerSync​

Create your Schema​

Create your Connector​

Create your PowerSync Plugin​

Kysely ORM (Optional)​

Enabling Diagnostics​

PowerSync Inspector​

Setup​

Features​

Sync Status​

Data Inspector​

Config Inspector​

Logs​

Nuxt Devtools​

Known Issues​

Development​

Local Testing​

Features

Installation

Quick Start

Setting up PowerSync

Create your Schema

Create your Connector

Create your PowerSync Plugin

Kysely ORM (Optional)

Enabling Diagnostics

PowerSync Inspector

Setup

Features

Sync Status

Data Inspector

Config Inspector

Logs

Nuxt Devtools

Known Issues

Development

Local Testing