[Package] PowerSync Nuxt Module #797

khawarizmus · 2025-12-15T10:22:54Z

This PR introduces a new nuxt package to offer first-class support for Nuxt with PowerSync.

The PR also introduces a new demo showcasing a reference implementation showing PowerSync + Nuxt 4 + Supabase

Add Nuxt module package
Add PowerSync x Nuxt x Supabase demo
Write the changset
Test a dev release outside the repo

… and initial setup

…plementation

…Supabase Todo List demo

changeset-bot · 2025-12-15T10:22:59Z

⚠️ No Changeset found

Latest commit: 30702fa

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

khawarizmus · 2025-12-15T10:23:45Z

Not sure what the chanset should include when releasing a new package

stevensJourney

Just sharing some initial comments for some items which stood out from an initial review.

demos/nuxt-supabase-todolist/components/AppHeader.vue

demos/nuxt-supabase-todolist/README.md

stevensJourney · 2025-12-29T09:14:45Z

demos/nuxt-supabase-todolist/README.md

+└── nuxt.config.ts            # Nuxt configuration
+```
+
+## Learn More


It would be nice if this demo had a local Supabase config and quickstart for local development - which can be used to start the demo in only a few commands - like the YJS Demo has here.

I have added all necessary files and instructions for this

demos/nuxt-supabase-todolist/nuxt.config.ts

demos/nuxt-supabase-todolist/package.json

stevensJourney · 2025-12-29T10:08:57Z

packages/nuxt/src/runtime/utils/AppSchema.ts

@@ -0,0 +1,27 @@
+import { column, Schema, Table } from '@powersync/web'
+
+export const local_bucket_data = new Table(


Nit: We typically name these kinds of constants in upper case.

I exported the names of the tables as a cost.

stevensJourney · 2025-12-29T10:13:00Z

packages/nuxt/src/runtime/utils/DynamicSchemaManager.ts

+/**
+ * Record fields from downloaded data, then build a schema from it.
+ */
+export class DynamicSchemaManager {


This looks like a copy from tools/diagnostics-app? It would be nice if we had this functionality in some shared location.

As per our discussion, it's not a 100% copy past since I had to make some parts reactive, but there is a proposale that would make all this code disappear powersync-ja/powersync-sqlite-core#155

packages/nuxt/src/runtime/utils/NuxtPowerSyncDatabase.ts

stevensJourney · 2025-12-29T10:17:22Z

packages/nuxt/src/runtime/utils/NuxtPowerSyncDatabase.ts

+      // override settings to disable multitab as we can't use it right now
+      // options.flags = {
+      //   ...options.flags,
+      //   enableMultiTabs: true, // to support multitabe we need to write our won worker implementation


If you're overriding the PowerSyncDatabase, it might be possible (with some minor modifications) to actually implement your own web worker implementation, using the current primitives, which contains the required sync hooks.

I have used the SharedWebStreamingSyncImplementation, which made the inspector work across tabs now. but because it is the only way to have it work with the official Nuxt devtools, I opted into overriding the settings to force multitab.

Another way would be to display an error and say that they have to use multitab but can still access the inspector via direct URL. This would require detecting that we are inside the devtool (which I think is possible)

stevensJourney · 2025-12-29T10:19:16Z

packages/nuxt/src/runtime/utils/RustClientInterceptor.ts

+import type { DynamicSchemaManager } from './DynamicSchemaManager'
+import type { Ref } from 'vue'
+/**
+ * Tracks per-byte and per-operation progress for the Rust client.


Just sharing this again. I'd really prefer we did not duplicate these implementations.

Addressed above

demos/nuxt-supabase-todolist/README.md

demos/nuxt-supabase-todolist/nuxt.config.ts

demos/nuxt-supabase-todolist/pages/login.vue

packages/nuxt/src/devtools.ts

packages/nuxt/src/runtime/composables/usePowerSyncInspectorDiagnostics.ts

LucDeCaf · 2025-12-30T09:08:05Z

scripts/reset-node-modules.ts

Not entirely sure what the benefit of a dedicated script is over using npx npkill or even rm -rf demos/**/node_modules

I quickly vibe-coded this to reset the entire monorepo, not only the demos, which allowed me to iterate faster when I was having dependency and build issues. It can be improved to delete the pnpm-lock file and other unnecessary folders like .nuxt inside the nuxt demo folder.

I don't mind removing it completely either, but I found it useful tbh, that's why I pushed it.

If we do plan on keeping this script, can we consider adding to the package.json https://github.com/powersync-ja/powersync-js/blob/main/package.json#L20-L21 ?

I have renamed the script to reset-repo and added it to the packagejson` file.

kept the logic and made it delete pnpm-lock files. I was thinking of making it also delete dist and lib folders as well as tsconfig.tsbuildinfo files. This would make it easier to reset -> install -> build

Let me know what you guys think

I like that idea. One thing to be wary of if we delete lib files is that some projects use/used lib as a source folder instead of a build folder. (IIRC I replaced one of those with a library folder, not sure if there's still more but worth considering.)

It might also be worth letting users choose which repos are cleaned. There's some similar looking logic in the demo management scripts if you feel like implementing this.

…ashboard link for Nuxt Supabase Todo List demo

…, README, and inspector layout

…encies

…e nuxt.config.ts accordingly

…move unused JSON type definitions from module.ts and usePowerSyncInspectorDiagnostics.ts

…osable usage examples

…nd add YAML schema reference in sync-rules.yaml

LucDeCaf · 2026-01-13T08:17:42Z

packages/nuxt/src/runtime/composables/usePowerSyncKysely.ts

I'm not sold on bundling the Kysely integration with the Nuxt package, if users want to use another ORM they would have to pay the price of both ORMs' bundles.

I agree with this. I will see how to optionally include the dependency and composable via a config flag.

I have made it so that the user has to explicitly opt in to use Kysely, and the composable won't be imported unless they do. The dependency is also optional, and if they opt in and don't have it installed, the module would error.

Chriztiaan · 2026-01-13T21:05:10Z

demos/nuxt-supabase-todolist/app.vue

@@ -0,0 +1,58 @@
+<template>


I'd suggest that we keep a consistent orders for templates/script blocks across all our components in this demo.

Good point. I have made things more consistent now.

Chriztiaan · 2026-01-13T21:18:38Z

demos/nuxt-supabase-todolist/pages/confirm.vue

+      return navigateTo('/')
+    }
+  },
+  { immediate: true },


A few of these watches that happen to be immediate:true, could be swapped by watchEffect() - https://vuejs.org/guide/essentials/watchers#watcheffect

This was addressed

Chriztiaan · 2026-01-13T21:24:27Z

demos/nuxt-supabase-todolist/pages/index.vue

+import type { Database, TaskRecord } from '~/powersync/AppSchema'
+
+const client = useSupabaseClient()
+const user = asyncComputed(async () => await client.auth.getUser().then(res => res.data.user))


This is not a built-in helper, it's from VueUse, which doesn't seem to be a dependency of this demo - I do see it as one for the nuxt package though. Are we autoinstalling it for projects? Or is it just leaking into this project from the package?

I would consider dropping it for the demo to make the demo easier to adopt.

Yes, the module installs VueUse automatically as we are using it in some components. I wouldn't worry about including it since it's a very common module.

This may be a slippery slope, generally we want our packages to be as slim as possible. If some of the other/bigger nuxt modules auto apply this dependency too maybe it's fine. But I wouldn't want us to be the only package that sneaks in a 1mb dependency that they didn't explicitly opt in for.

Can you confirm which version is applied if you install a differing VueUse version in the demo too? Conflicts, or is one prioritised over the other?

Chriztiaan · 2026-01-13T21:35:13Z

demos/nuxt-supabase-todolist/package.json

+  "dependencies": {
+    "@nuxt/ui": "^4.0.0",
+    "@nuxtjs/supabase": "2.0.1",
+    "@powersync/nuxt": "workspace:*",


Our demos no longer depend on workspace dependencies, after this PR is approved we may need to split the work into two PRs to a release out that this demo can depend on.

…clarify diagnostics schema usage

…ate related constants

…s, and remove obsolete reset-node-modules script

# Conflicts: # packages/web/src/index.ts # pnpm-lock.yaml

…ngle version

…, improving code readability and structure

…rm.vue

…spector-layout for improved loading experience

… usePowerSyncInspectorDiagnostics

Amine added 5 commits December 11, 2025 00:28

feat: added nuxt module

db1ecce

feat: add Nuxt Supabase Todo List demo with environment configuration…

e5c95ac

… and initial setup

feat: prepare NuxtPowerSyncDatabase to support default sync client im…

3521b82

…plementation

feat: add environment configuration template and sync rules for Nuxt …

c58db3c

…Supabase Todo List demo

feat: add README and update seed.sql for Nuxt Supabase Todo List demo

5771c58

khawarizmus requested review from Chriztiaan, LucDeCaf, rkistner, simolus3 and stevensJourney December 15, 2025 10:22

stevensJourney reviewed Dec 29, 2025

View reviewed changes

LucDeCaf reviewed Dec 30, 2025

View reviewed changes

Amine added 8 commits January 12, 2026 13:12

docs: update README with secure password note and correct PowerSync d…

07a9c27

…ashboard link for Nuxt Supabase Todo List demo

feat: add powersync-icon.svg asset and update references in AppHeader…

7c52649

…, README, and inspector layout

chore: update package.json to include @supabase/supabase-js in depend…

a67886d

…encies

chore: remove vite-plugin-top-level-await from dependencies and updat…

d67a0fe

…e nuxt.config.ts accordingly

fix: update login button text to use consistent capitalization and re…

6e3e768

…move unused JSON type definitions from module.ts and usePowerSyncInspectorDiagnostics.ts

docs: clean up README by removing outdated comments and updating comp…

e5219b9

…osable usage examples

docs: add Nuxt Module to Docosorus

d2bd1c3

chore: update pnpm-lock.yaml to reflect dependency version upgrades a…

e3b04e5

…nd add YAML schema reference in sync-rules.yaml

LucDeCaf reviewed Jan 13, 2026

View reviewed changes

Chriztiaan reviewed Jan 13, 2026

View reviewed changes

Amine added 3 commits January 15, 2026 12:06

refactor: remove the need to add diagnostics schema manually

5883058

docs: update README to reflect removal of top-level await plugin and …

2bda6eb

…clarify diagnostics schema usage

refactor: standardize table names to lowercase in SQL queries and upd…

49060a0

…ate related constants

Amine added 13 commits January 15, 2026 16:12

feat: added multitab support

510a96f

chore: add reset:repo script to clean node_modules and pnpm lock file…

6363f30

…s, and remove obsolete reset-node-modules script

chore: update author name in package.json from JOURNEYAPPS to POWERSYNC

35490f8

Merge branch 'main' into nuxt

30062cc

# Conflicts: # packages/web/src/index.ts # pnpm-lock.yaml

chore: lay the ground for demo Isolation

dd7181c

fix: removed vue deps from demo project to allow pnpm to resolve a si…

754581d

…ngle version

feat: made Kysely integration in Nuxt module optional

fb28c97

feat: added local development guide with supabase

4d5ff6c

refactor: clean up and reorganize Vue components in the todolist demo…

a65a509

…, improving code readability and structure

refactor: replace watch with watchEffect for user navigation in confi…

18b4319

…rm.vue

feat: add LoadingSpinner component and integrate it into powersync-in…

9c2fe9e

…spector-layout for improved loading experience

fix: fixed flickering cause by icon size change when status change

4d57259

feat: define BucketRow and TableRow types for improved type safety in…

30702fa

… usePowerSyncInspectorDiagnostics

		@@ -0,0 +1,27 @@
		import { column, Schema, Table } from '@powersync/web'

		export const local_bucket_data = new Table(

[Package] PowerSync Nuxt Module #797

Are you sure you want to change the base?

[Package] PowerSync Nuxt Module #797

Uh oh!

Conversation

khawarizmus commented Dec 15, 2025

Uh oh!

changeset-bot bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

khawarizmus commented Dec 15, 2025

Uh oh!

stevensJourney left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Chriztiaan Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

changeset-bot bot commented Dec 15, 2025 •

edited

Loading

Chriztiaan Jan 13, 2026 •

edited

Loading