Skip to content

Open source personal finance application

perf(powersync): lazy-load @powersync/web out of the entry chunk

Ilya Komichevd0061f04c53c
diff --git a/app/app/components/user/useUserStore.test.ts b/app/app/components/user/useUserStore.test.ts
index 804ac555..c629a88d 100644
--- a/app/app/components/user/useUserStore.test.ts
+++ b/app/app/components/user/useUserStore.test.ts
@@ -10,14 +10,14 @@ const h = vi.hoisted(() => ({
deleteRow: vi.fn(),
demo: { value: false },
disconnectPowerSync: vi.fn(async () => true),
+ getPowerSyncDb: vi.fn(async () => ({ execute: vi.fn() })),
upsertRow: vi.fn(),
upsertRows: vi.fn(),
- usePowerSyncDb: vi.fn(() => ({ execute: vi.fn() })),
watchTable: vi.fn(() => ({ abort: vi.fn() })),
}))
vi.mock('localforage', () => ({ default: { clear: vi.fn(), getItem: vi.fn(), removeItem: vi.fn(), setItem: vi.fn() } }))
-vi.mock('~~/services/powersync/db', () => ({ disconnectPowerSync: h.disconnectPowerSync, usePowerSyncDb: h.usePowerSyncDb, watchTable: h.watchTable }))
+vi.mock('~~/services/powersync/db', () => ({ disconnectPowerSync: h.disconnectPowerSync, getPowerSyncDb: h.getPowerSyncDb, watchTable: h.watchTable }))
vi.mock('~~/services/powersync/mutations', () => ({ deleteRow: h.deleteRow, upsertRow: h.upsertRow, upsertRows: h.upsertRows }))
vi.mock('~/components/demo/useDemo', () => ({ useDemo: () => ({ isDemo: h.demo }) }))
vi.mock('~/composables/useSupabase', () => ({ useSupabase: () => ({}), useSupabaseAuth: () => h.auth }))
diff --git a/app/app/components/user/useUserStore.ts b/app/app/components/user/useUserStore.ts
index 0147bd7d..c015d19d 100644
--- a/app/app/components/user/useUserStore.ts
+++ b/app/app/components/user/useUserStore.ts
@@ -1,7 +1,7 @@
import type { Row } from '~~/services/powersync/transforms'
import localforage from 'localforage'
-import { disconnectPowerSync, usePowerSyncDb, watchTable } from '~~/services/powersync/db'
+import { disconnectPowerSync, getPowerSyncDb, watchTable } from '~~/services/powersync/db'
import { upsertRow } from '~~/services/powersync/mutations'
import type { CurrencyCode } from '~/components/currencies/types'
@@ -270,7 +270,7 @@ export const useUserStore = defineStore('user', () => {
}
try {
- const db = usePowerSyncDb()
+ const db = await getPowerSyncDb()
await db.execute('DELETE FROM trns')
await db.execute('DELETE FROM categories')
await db.execute('DELETE FROM wallets')
diff --git a/app/app/plugins/powersync.client.ts b/app/app/plugins/powersync.client.ts
index cdc296a0..7edd68fa 100644
--- a/app/app/plugins/powersync.client.ts
+++ b/app/app/plugins/powersync.client.ts
@@ -1,6 +1,6 @@
-import { setUploadErrorHandler } from '~~/services/powersync/connector'
-import { connectPowerSync, disconnectPowerSync, forceResync, usePowerSyncDb } from '~~/services/powersync/db'
+import { connectPowerSync, disconnectPowerSync, forceResync, getPowerSyncDb } from '~~/services/powersync/db'
import { deleteRow } from '~~/services/powersync/mutations'
+import { setUploadErrorHandler } from '~~/services/powersync/uploadErrorHandler'
import { planDivergence } from '~~/services/powersync/uploadReconcile'
import { useDemo } from '~/components/demo/useDemo'
@@ -24,7 +24,7 @@ export default defineNuxtPlugin(() => {
// Open local SQLite immediately for an already-logged-in user so the cold-start DB
// init overlaps app boot instead of waiting for the async session to resolve.
if (!isDemo.value && hasPersistedSession())
- usePowerSyncDb().init().catch(e => logger.error('eager db init failed', e))
+ getPowerSyncDb().then(db => db.init()).catch(e => logger.error('eager db init failed', e))
// Reconcile local rows after a write was fatally rejected by the server and discarded.
setUploadErrorHandler((_error, divergedOps) => {
diff --git a/app/services/powersync/connector.test.ts b/app/services/powersync/connector.test.ts
index 0d266818..30eed29c 100644
--- a/app/services/powersync/connector.test.ts
+++ b/app/services/powersync/connector.test.ts
@@ -1,7 +1,8 @@
import type { SupabaseClient } from '@supabase/supabase-js'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { setUploadErrorHandler, SupabaseConnector } from '~~/services/powersync/connector'
+import { SupabaseConnector } from '~~/services/powersync/connector'
+import { setUploadErrorHandler } from '~~/services/powersync/uploadErrorHandler'
vi.mock('@powersync/web', () => ({
UpdateType: { DELETE: 'DELETE', PATCH: 'PATCH', PUT: 'PUT' },
diff --git a/app/services/powersync/connector.ts b/app/services/powersync/connector.ts
index 77333fd6..c4d2449d 100644
--- a/app/services/powersync/connector.ts
+++ b/app/services/powersync/connector.ts
@@ -1,6 +1,5 @@
import type {
AbstractPowerSyncDatabase,
- CrudEntry,
PowerSyncBackendConnector,
PowerSyncCredentials,
} from '@powersync/web'
@@ -10,6 +9,8 @@ import { UpdateType } from '@powersync/web'
import { createLogger } from '~/utils/logger'
+import { notifyFatalUploadError } from './uploadErrorHandler'
+
const logger = createLogger('powersync-connector')
// Postgres error codes that retrying can't fix - the op is discarded, not requeued forever.
@@ -19,17 +20,6 @@ const FATAL_RESPONSE_CODES = [
/^42501$/, // insufficient privilege (RLS violation)
]
-type UploadErrorHandler = (error: Error, divergedOps: CrudEntry[]) => void
-
-// Surfaces fatal (discarded) upload errors to the app; set once from the PowerSync
-// plugin so the connector stays free of UI/i18n coupling. The handler reconciles the
-// discarded ops (revert rejected inserts / offer a reload for rejected updates+deletes).
-let _onFatalUploadError: UploadErrorHandler | null = null
-
-export function setUploadErrorHandler(handler: UploadErrorHandler | null): void {
- _onFatalUploadError = handler
-}
-
/**
* Bridges PowerSync's local write queue to Supabase:
* - `fetchCredentials` provides the PowerSync endpoint + the current Supabase JWT.
@@ -93,7 +83,7 @@ export class SupabaseConnector implements PowerSyncBackendConnector {
// never reached the server, so only those diverge and need reconciling.
const divergedOps = transaction.crud.slice(failedIndex)
logger.error('discarding fatal upload error', divergedOps, ex)
- _onFatalUploadError?.(ex, divergedOps)
+ notifyFatalUploadError(ex, divergedOps)
await transaction.complete()
}
else {
diff --git a/app/services/powersync/db.ts b/app/services/powersync/db.ts
index 8cb82abd..9e0d6129 100644
--- a/app/services/powersync/db.ts
+++ b/app/services/powersync/db.ts
@@ -1,15 +1,12 @@
+import type { PowerSyncDatabase } from '@powersync/web'
import type { SupabaseClient } from '@supabase/supabase-js'
-import { PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS } from '@powersync/web'
-
import { createLogger } from '~/utils/logger'
-import { AppSchema } from './AppSchema'
-import { SupabaseConnector } from './connector'
-
const logger = createLogger('powersync')
let _db: PowerSyncDatabase | null = null
+let _dbPromise: Promise<PowerSyncDatabase> | null = null
let _connected = false
// Serializes connect/wipe so the plugin watcher and the data-load path can't race into a double wipe.
let _connectQueue: Promise<void> = Promise.resolve()
@@ -44,9 +41,17 @@ function clearLocalDbOwner(): void {
catch {}
}
-/** Singleton PowerSync database (local SQLite, WASM + IndexedDB VFS: multi-tab, no COOP/COEP). */
-export function usePowerSyncDb(): PowerSyncDatabase {
- if (!_db) {
+/**
+ * Singleton PowerSync database (local SQLite, WASM + IndexedDB VFS: multi-tab, no COOP/COEP).
+ * `@powersync/web` (+ schema) is dynamically imported on first call so its ~300KB stays out of
+ * the entry chunk - the login page and demo mode never parse it.
+ */
+export function getPowerSyncDb(): Promise<PowerSyncDatabase> {
+ _dbPromise ??= (async () => {
+ const [{ PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS }, { AppSchema }] = await Promise.all([
+ import('@powersync/web'),
+ import('./AppSchema'),
+ ])
_db = new PowerSyncDatabase({
database: new WASQLiteOpenFactory({
dbFilename: 'finapp.db',
@@ -54,13 +59,14 @@ export function usePowerSyncDb(): PowerSyncDatabase {
}),
schema: AppSchema,
})
- }
- return _db
+ return _db
+ })()
+ return _dbPromise
}
/** Disconnect and wipe local SQLite, resetting connection + owner state. */
async function wipeLocalDb(): Promise<void> {
- const db = usePowerSyncDb()
+ const db = await getPowerSyncDb()
await db.disconnectAndClear()
_connected = false
clearLocalDbOwner()
@@ -68,7 +74,10 @@ async function wipeLocalDb(): Promise<void> {
}
async function doConnect(client: SupabaseClient, powerSyncUrl: string, userId: string): Promise<void> {
- const db = usePowerSyncDb()
+ const [db, { SupabaseConnector }] = await Promise.all([
+ getPowerSyncDb(),
+ import('./connector'),
+ ])
// Cross-user guard: wipe another user's rows before connecting. Fail closed -
// if the wipe throws we do NOT connect, so the new user can't read stale data.
const owner = getLocalDbOwner()
@@ -117,13 +126,14 @@ export function forceResync(client: SupabaseClient, powerSyncUrl: string, userId
* on failure the owner marker is kept so the next foreign sign-in wipes first.
*/
export async function disconnectPowerSync(): Promise<boolean> {
- if (!_db) {
+ if (!_dbPromise) {
clearLocalDbOwner()
return true
}
_connected = false
try {
- await _db.disconnectAndClear()
+ const db = await _dbPromise
+ await db.disconnectAndClear()
clearLocalDbOwner()
logger.log('disconnected and cleared')
return true
@@ -136,7 +146,7 @@ export async function disconnectPowerSync(): Promise<boolean> {
/** Resolves `true` once the first full sync completes; `false` on timeout / not connected. */
export async function waitForFirstSync(timeoutMs = 30000): Promise<boolean> {
- const db = usePowerSyncDb()
+ const db = await getPowerSyncDb()
if (db.currentStatus?.hasSynced)
return true
const controller = new AbortController()
@@ -154,7 +164,7 @@ export async function waitForFirstSync(timeoutMs = 30000): Promise<boolean> {
}
export async function hasAnyLocalData(): Promise<boolean> {
- const db = usePowerSyncDb()
+ const db = await getPowerSyncDb()
for (const table of ['wallets', 'categories', 'trns'] as const) {
const row = await db.get<{ c: number }>(`SELECT count(*) as c FROM ${table}`)
if ((row?.c ?? 0) > 0)
@@ -173,19 +183,37 @@ export function watchTable<TRow = Record<string, unknown>>(
onRows: (rows: TRow[]) => void,
throttleMs?: number,
): AbortController {
- const db = usePowerSyncDb()
const controller = new AbortController()
- db.watch(
- sql,
- params,
- {
- onError: (e: Error) => logger.error(`watch error: ${sql}`, e),
- onResult: (result: { rows?: { _array: unknown[] } }) => {
- onRows((result.rows?._array ?? []) as TRow[])
- },
- },
- // PowerSync coalesces table-change events within `throttleMs` (default 30ms) into one re-query.
- { signal: controller.signal, ...(throttleMs != null ? { throttleMs } : {}) },
- )
+ // Cold-start instrumentation: `performance.measure('ps:watch:<label>')` spans subscribe ->
+ // first emission, exposing how the boot queries serialize on the single worker connection.
+ const label = sql.replace(/SELECT \* FROM /, '').slice(0, 32)
+ performance.mark(`ps:watch:${label}:queued`)
+ let isFirstEmit = true
+ getPowerSyncDb()
+ .then((db) => {
+ if (controller.signal.aborted)
+ return
+ performance.mark(`ps:watch:${label}:armed`)
+ db.watch(
+ sql,
+ params,
+ {
+ onError: (e: Error) => logger.error(`watch error: ${sql}`, e),
+ onResult: (result: { rows?: { _array: unknown[] } }) => {
+ const rows = (result.rows?._array ?? []) as TRow[]
+ if (isFirstEmit) {
+ isFirstEmit = false
+ performance.mark(`ps:watch:${label}:first`)
+ performance.measure(`ps:watch:${label}`, `ps:watch:${label}:queued`, `ps:watch:${label}:first`)
+ logger.log(`first emit ${label}: ${rows.length} rows`)
+ }
+ onRows(rows)
+ },
+ },
+ // PowerSync coalesces table-change events within `throttleMs` (default 30ms) into one re-query.
+ { signal: controller.signal, ...(throttleMs != null ? { throttleMs } : {}) },
+ )
+ })
+ .catch((e: unknown) => logger.error(`watch start failed: ${sql}`, e))
return controller
}
diff --git a/app/services/powersync/mutations.ts b/app/services/powersync/mutations.ts
index 33ff9851..0ff1e1a0 100644
--- a/app/services/powersync/mutations.ts
+++ b/app/services/powersync/mutations.ts
@@ -1,6 +1,6 @@
import type { LockContext } from '@powersync/web'
-import { usePowerSyncDb } from './db'
+import { getPowerSyncDb } from './db'
// PowerSync client tables are SQLite views with INSTEAD OF triggers: they take plain
// INSERT/UPDATE/DELETE but not `INSERT ... ON CONFLICT`, so upsert = existence check + INSERT/UPDATE.
@@ -42,19 +42,22 @@ async function upsertWith(
*/
export async function upsertRow(table: string, id: string, row: Record<string, unknown>): Promise<void> {
// Existence check + INSERT/UPDATE in one transaction (atomic, single lock).
- await usePowerSyncDb().writeTransaction(async (tx) => {
+ const db = await getPowerSyncDb()
+ await db.writeTransaction(async (tx) => {
await upsertWith(tx, table, id, row)
})
}
export async function deleteRow(table: string, id: string): Promise<void> {
assertTable(table)
- await usePowerSyncDb().execute(`DELETE FROM ${table} WHERE id = ?`, [id])
+ const db = await getPowerSyncDb()
+ await db.execute(`DELETE FROM ${table} WHERE id = ?`, [id])
}
/** Upsert several rows in a single write transaction (e.g. wallet reordering). */
export async function upsertRows(table: string, rows: { id: string, row: Record<string, unknown> }[]): Promise<void> {
- await usePowerSyncDb().writeTransaction(async (tx) => {
+ const db = await getPowerSyncDb()
+ await db.writeTransaction(async (tx) => {
for (const { id, row } of rows)
await upsertWith(tx, table, id, row)
})
diff --git a/app/services/powersync/uploadErrorHandler.ts b/app/services/powersync/uploadErrorHandler.ts
new file mode 100644
index 00000000..15ac2c10
--- /dev/null
+++ b/app/services/powersync/uploadErrorHandler.ts
@@ -0,0 +1,17 @@
+import type { CrudEntry } from '@powersync/web'
+
+type UploadErrorHandler = (error: Error, divergedOps: CrudEntry[]) => void
+
+// Surfaces fatal (discarded) upload errors to the app; set once from the PowerSync plugin
+// so the connector stays free of UI/i18n coupling. Lives outside connector.ts because the
+// plugin imports it statically - connector.ts has runtime @powersync/web imports and must
+// stay reachable only through the dynamic import in db.ts (entry-chunk size).
+let _onFatalUploadError: UploadErrorHandler | null = null
+
+export function setUploadErrorHandler(handler: UploadErrorHandler | null): void {
+ _onFatalUploadError = handler
+}
+
+export function notifyFatalUploadError(error: Error, divergedOps: CrudEntry[]): void {
+ _onFatalUploadError?.(error, divergedOps)
+}
diff --git a/app/services/powersync/uploadReconcile.test.ts b/app/services/powersync/uploadReconcile.test.ts
index f42875f0..26c327c6 100644
--- a/app/services/powersync/uploadReconcile.test.ts
+++ b/app/services/powersync/uploadReconcile.test.ts
@@ -1,7 +1,6 @@
import type { CrudEntry } from '@powersync/web'
import { describe, expect, it, vi } from 'vitest'
-
import { planDivergence } from '~~/services/powersync/uploadReconcile'
vi.mock('@powersync/web', () => ({
diff --git a/app/services/powersync/uploadReconcile.ts b/app/services/powersync/uploadReconcile.ts
index 89b10f65..52a97fd0 100644
--- a/app/services/powersync/uploadReconcile.ts
+++ b/app/services/powersync/uploadReconcile.ts
@@ -1,7 +1,5 @@
import type { CrudEntry } from '@powersync/web'
-import { UpdateType } from '@powersync/web'
-
export type DivergencePlan = {
/** True when any non-PUT op diverged; only a full re-sync can restore those. */
needsReload: boolean
@@ -21,7 +19,9 @@ export function planDivergence(divergedOps: CrudEntry[]): DivergencePlan {
if (!divergedOps.length)
return { needsReload: false, toRevert: [] }
- const allPut = divergedOps.every(op => op.op === UpdateType.PUT)
+ // String literal instead of the UpdateType enum: a runtime import here would statically
+ // pull @powersync/web into the entry chunk via the plugin (it stays lazy, see db.ts).
+ const allPut = divergedOps.every(op => (op.op as string) === 'PUT')
if (!allPut)
return { needsReload: true, toRevert: [] }