feat: add Tauri sqlite persisted collection package (#1369)

* feat: add Tauri sqlite persisted collection package

Wrap the official Tauri SQL plugin in the shared SQLite persistence layer so persisted collections can run in Tauri apps without shipping repo-owned Rust code. Add contract coverage and a real Tauri conformance harness to validate the runtime integration end to end.

Made-with: Cursor

* fix: add missing tauri persistence coverage and clean e2e lockfile

Add runtime persistence contract and integration tests for the Tauri package, expand placeholder parser edge-case coverage, drop unused jsx tsconfig option, and stop tracking the e2e Cargo.lock. Also refresh pnpm-lock.yaml so lockfile validation succeeds.

Made-with: Cursor

* lock file

* format

* fix: exclude tauri e2e build artifacts from ts checking

Prevent the tauri e2e app tsconfig from checking emitted dist JavaScript so CI does not report implicit-any and nullable errors against bundled output.

Made-with: Cursor

* fix: scope tauri tsconfig to source TypeScript files

Avoid including generated e2e app build artifacts in Vitest typechecking by narrowing e2e includes to TypeScript and excluding app dist/target outputs.

Made-with: Cursor

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: samwillis

packages/db-tauri-sqlite-persisted-collection/README.md

@@ -0,0 +1,96 @@
+# @tanstack/db-tauri-sqlite-persisted-collection
+
+Thin SQLite persistence for Tauri apps using `@tauri-apps/plugin-sql`.
+
+## Public API
+
+- `createTauriSQLitePersistence(...)`
+- `persistedCollectionOptions(...)` (re-exported from core)
+
+## Install
+
+```bash
+pnpm add @tanstack/db-tauri-sqlite-persisted-collection @tauri-apps/plugin-sql
+```
+
+## Consumer-side Tauri setup
+
+Install the official SQL plugin in your Tauri app:
+
+```bash
+cd src-tauri
+cargo add tauri-plugin-sql --features sqlite
+```
+
+Register the plugin in `src-tauri/src/main.rs`:
+
+```rust
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_sql::Builder::default().build())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+Enable the SQL permissions in `src-tauri/capabilities/default.json`:
+
+```json
+{
+  "permissions": ["core:default", "sql:default", "sql:allow-execute"]
+}
+```
+
+## Quick start
+
+```ts
+import Database from '@tauri-apps/plugin-sql'
+import { createCollection } from '@tanstack/db'
+import {
+  createTauriSQLitePersistence,
+  persistedCollectionOptions,
+} from '@tanstack/db-tauri-sqlite-persisted-collection'
+
+type Todo = {
+  id: string
+  title: string
+  completed: boolean
+}
+
+const database = await Database.load(`sqlite:tanstack-db.sqlite`)
+
+const persistence = createTauriSQLitePersistence({
+  database,
+})
+
+export const todosCollection = createCollection(
+  persistedCollectionOptions<Todo, string>({
+    id: `todos`,
+    getKey: (todo) => todo.id,
+    persistence,
+    schemaVersion: 1,
+  }),
+)
+```
+
+## Notes
+
+- `createTauriSQLitePersistence` is shared across collections.
+- Reuse a single `Database.load('sqlite:...')` handle per SQLite file when using
+  this package. Opening multiple plugin handles to the same file can reintroduce
+  SQLite locking behavior outside this package's serialized transaction queue.
+- Mode defaults (`sync-present` vs `sync-absent`) are inferred from whether a
+  `sync` config is present in `persistedCollectionOptions`.
+- This package expects a database handle created by
+  `@tauri-apps/plugin-sql`, typically from `Database.load('sqlite:...')`.
+- The database path is resolved by Tauri's SQL plugin, not by this package.
+- This package does not publish or require package-specific Rust code. Only the
+  app-level Tauri SQL plugin registration shown above is required.
+
+## Testing
+
+- `pnpm --filter @tanstack/db-tauri-sqlite-persisted-collection test`
+  runs the driver and shared adapter contract tests.
+- `pnpm --filter @tanstack/db-tauri-sqlite-persisted-collection test:e2e`
+  builds the repo-local Tauri harness and runs the persisted collection
+  conformance suite inside a real Tauri runtime.

packages/db-tauri-sqlite-persisted-collection/e2e/app/index.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Tauri SQLite E2E</title>
+  </head>
+  <body>
+    <main>
+      <p id="status">Booting Tauri persisted collection e2e runtime</p>
+      <pre id="details"></pre>
+    </main>
+    <script type="module">
+      const reportUrl = '%VITE_TANSTACK_DB_TAURI_E2E_REPORT_URL%'
+
+      if (reportUrl && !reportUrl.startsWith('%')) {
+        fetch(reportUrl, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+          },
+          body: JSON.stringify({
+            kind: 'status',
+            phase: 'html-loaded',
+          }),
+        }).catch(() => {})
+      }
+
+      import('/src/main.ts').catch((error) => {
+        if (reportUrl && !reportUrl.startsWith('%')) {
+          fetch(reportUrl, {
+            method: 'POST',
+            headers: {
+              'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+              kind: 'status',
+              phase: 'main-import-failed',
+              details: {
+                message: String(error?.message ?? error),
+              },
+            }),
+          }).catch(() => {})
+        }
+      })
+    </script>
+  </body>
+</html>

packages/db-tauri-sqlite-persisted-collection/e2e/app/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@tanstack/db-tauri-sqlite-persisted-collection-e2e-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "tauri": "tauri"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "^2.10.1",
+    "@tauri-apps/plugin-sql": "^2.3.2",
+    "@tanstack/db": "workspace:*",
+    "@tanstack/db-tauri-sqlite-persisted-collection": "workspace:*"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.10.1",
+    "@types/node": "^25.2.2",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  }
+}

packages/db-tauri-sqlite-persisted-collection/e2e/app/src-tauri/.gitignore

@@ -0,0 +1,3 @@
+/target
+/gen
+/Cargo.lock

packages/db-tauri-sqlite-persisted-collection/e2e/app/src-tauri/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "db-tauri-sqlite-persisted-collection-e2e-app"
+version = "0.0.0"
+description = "Repo-local Tauri e2e harness for TanStack DB SQLite persistence"
+authors = ["TanStack Team"]
+edition = "2021"
+
+[build-dependencies]
+tauri-build = { version = "2.5.6", features = [] }
+
+[dependencies]
+serde_json = "1"
+tauri = { version = "2.10.3", features = [] }
+tauri-plugin-sql = { version = "2.3.2", features = ["sqlite"] }

packages/db-tauri-sqlite-persisted-collection/e2e/app/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+  tauri_build::build()
+}

packages/db-tauri-sqlite-persisted-collection/e2e/app/src-tauri/capabilities/default.json

@@ -0,0 +1,6 @@
+{
+  "identifier": "default",
+  "description": "Default capability for the Tauri SQLite e2e harness",
+  "windows": ["main"],
+  "permissions": ["core:default", "sql:default", "sql:allow-execute"]
+}

packages/db-tauri-sqlite-persisted-collection/e2e/app/src-tauri/icons/icon.png

@@ -0,0 +1,8 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_sql::Builder::default().build())
+        .run(tauri::generate_context!())
+        .expect("error while running Tauri e2e application");
+}

packages/db-tauri-sqlite-persisted-collection/e2e/app/src-tauri/src/main.rs

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "TanStack DB Tauri E2E",
+  "version": "0.0.0",
+  "identifier": "com.tanstack.db.tauri.e2e",
+  "build": {
+    "beforeDevCommand": "pnpm dev --host 127.0.0.1 --port 1420",
+    "devUrl": "http://127.0.0.1:1420",
+    "frontendDist": "../dist"
+  },
+  "app": {
+    "windows": [
+      {
+        "title": "TanStack DB Tauri E2E",
+        "width": 1280,
+        "height": 900
+      }
+    ],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": false,
+    "icon": []
+  }
+}