feat(offline-transactions): implement offline-first transaction system

.changeset/offline-transactions-initial.md

@@ -0,0 +1,69 @@
+---
+"@tanstack/offline-transactions": minor
+"@tanstack/db": patch
+---
+
+Add offline-transactions package with robust offline-first capabilities
+
+New package `@tanstack/offline-transactions` provides a comprehensive offline-first transaction system with:
+
+**Core Features:**
+
+- Persistent outbox pattern for reliable transaction processing
+- Leader election for multi-tab coordination (Web Locks API with BroadcastChannel fallback)
+- Automatic storage capability detection with graceful degradation
+- Retry logic with exponential backoff and jitter
+- Sequential transaction processing (FIFO ordering)
+
+**Storage:**
+
+- Automatic fallback chain: IndexedDB → localStorage → online-only
+- Detects and handles private mode, SecurityError, QuotaExceededError
+- Custom storage adapter support
+- Diagnostic callbacks for storage failures
+
+**Developer Experience:**
+
+- TypeScript-first with full type safety
+- Comprehensive test suite (25 tests covering leader failover, storage failures, e2e scenarios)
+- Works in all modern browsers and server-side rendering environments
+
+**@tanstack/db improvements:**
+
+- Enhanced duplicate instance detection (dev-only, iframe-aware, with escape hatch)
+- Better environment detection for SSR and worker contexts
+
+Example usage:
+
+```typescript
+import {
+  startOfflineExecutor,
+  IndexedDBAdapter,
+} from "@tanstack/offline-transactions"
+
+const executor = startOfflineExecutor({
+  collections: { todos: todoCollection },
+  storage: new IndexedDBAdapter(),
+  mutationFns: {
+    syncTodos: async ({ transaction, idempotencyKey }) => {
+      // Sync mutations to backend
+      await api.sync(transaction.mutations, idempotencyKey)
+    },
+  },
+  onStorageFailure: (diagnostic) => {
+    console.warn("Running in online-only mode:", diagnostic.message)
+  },
+})
+
+// Create offline transaction
+const tx = executor.createOfflineTransaction({
+  mutationFnName: "syncTodos",
+  autoCommit: false,
+})
+
+tx.mutate(() => {
+  todoCollection.insert({ id: "1", text: "Buy milk", completed: false })
+})
+
+await tx.commit() // Persists to outbox and syncs when online
+```

.pnpmfile.cjs

@@ -0,0 +1,25 @@
+function readPackage(pkg, context) {
+  // Force all @tanstack/db dependencies to resolve to workspace version
+  if (pkg.dependencies && pkg.dependencies["@tanstack/db"]) {
+    pkg.dependencies["@tanstack/db"] = "workspace:*"
+    context.log(`Overriding @tanstack/db dependency in ${pkg.name}`)
+  }
+
+  if (pkg.devDependencies && pkg.devDependencies["@tanstack/db"]) {
+    pkg.devDependencies["@tanstack/db"] = "workspace:*"
+    context.log(`Overriding @tanstack/db devDependency in ${pkg.name}`)
+  }
+
+  if (pkg.peerDependencies && pkg.peerDependencies["@tanstack/db"]) {
+    pkg.peerDependencies["@tanstack/db"] = "workspace:*"
+    context.log(`Overriding @tanstack/db peerDependency in ${pkg.name}`)
+  }
+
+  return pkg
+}
+
+module.exports = {
+  hooks: {
+    readPackage,
+  },
+}

examples/react/offline-transactions/.env.example

@@ -0,0 +1,3 @@
+# Honeycomb API Key
+# Get your API key from https://ui.honeycomb.io/account
+HONEYCOMB_API_KEY=your_api_key_here

examples/react/offline-transactions/.gitignore

@@ -0,0 +1,20 @@
+node_modules
+package-lock.json
+yarn.lock
+
+.DS_Store
+.cache
+.env
+.vercel
+.output
+.nitro
+/build/
+/api/
+/server/build
+/public/build# Sentry Config File
+.env.sentry-build-plugin
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+.tanstack

examples/react/offline-transactions/.prettierignore

@@ -0,0 +1,4 @@
+**/build
+**/public
+pnpm-lock.yaml
+routeTree.gen.ts

examples/react/offline-transactions/README.md

@@ -0,0 +1,72 @@
+# Welcome to TanStack.com!
+
+This site is built with TanStack Router!
+
+- [TanStack Router Docs](https://tanstack.com/router)
+
+It's deployed automagically with Netlify!
+
+- [Netlify](https://netlify.com/)
+
+## Development
+
+From your terminal:
+
+```sh
+pnpm install
+pnpm dev
+```
+
+This starts your app in development mode, rebuilding assets on file changes.
+
+## Editing and previewing the docs of TanStack projects locally
+
+The documentations for all TanStack projects except for `React Charts` are hosted on [https://tanstack.com](https://tanstack.com), powered by this TanStack Router app.
+In production, the markdown doc pages are fetched from the GitHub repos of the projects, but in development they are read from the local file system.
+
+Follow these steps if you want to edit the doc pages of a project (in these steps we'll assume it's [`TanStack/form`](https://github.com/tanstack/form)) and preview them locally :
+
+1. Create a new directory called `tanstack`.
+
+```sh
+mkdir tanstack
+```
+
+2. Enter the directory and clone this repo and the repo of the project there.
+
+```sh
+cd tanstack
+git clone [email protected]:TanStack/tanstack.com.git
+git clone [email protected]:TanStack/form.git
+```
+
+> [!NOTE]
+> Your `tanstack` directory should look like this:
+>
+> ```
+> tanstack/
+>    |
+>    +-- form/
+>    |
+>    +-- tanstack.com/
+> ```
+
+> [!WARNING]
+> Make sure the name of the directory in your local file system matches the name of the project's repo. For example, `tanstack/form` must be cloned into `form` (this is the default) instead of `some-other-name`, because that way, the doc pages won't be found.
+
+3. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
+
+```sh
+cd tanstack.com
+pnpm i
+# The app will run on https://localhost:3000 by default
+pnpm dev
+```
+
+4. Now you can visit http://localhost:3000/form/latest/docs/overview in the browser and see the changes you make in `tanstack/form/docs`.
+
+> [!NOTE]
+> The updated pages need to be manually reloaded in the browser.
+
+> [!WARNING]
+> You will need to update the `docs/config.json` file (in the project's repo) if you add a new doc page!

examples/react/offline-transactions/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "tanstack-start-example-basic",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "start": "node .output/server/index.mjs"
+  },
+  "dependencies": {
+    "@tanstack/offline-transactions": "workspace:*",
+    "@tanstack/query-db-collection": "workspace:*",
+    "@tanstack/react-db": "workspace:*",
+    "@tanstack/react-query": "^5.89.0",
+    "@tanstack/react-router": "^1.131.47",
+    "@tanstack/react-router-devtools": "^1.131.47",
+    "@tanstack/react-start": "^1.131.47",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwind-merge": "^2.6.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^5.0.3",
+    "autoprefixer": "^10.4.20",
+    "chokidar": "^4.0.3",
+    "postcss": "^8.5.1",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "vite": "^7.1.7",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

examples/react/offline-transactions/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

examples/react/offline-transactions/public/site.webmanifest

@@ -0,0 +1,19 @@
+{
+  "name": "",
+  "short_name": "",
+  "icons": [
+    {
+      "src": "/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/android-chrome-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

examples/react/offline-transactions/src/components/DefaultCatchBoundary.tsx

@@ -0,0 +1,53 @@
+import {
+  ErrorComponent,
+  Link,
+  rootRouteId,
+  useMatch,
+  useRouter,
+} from "@tanstack/react-router"
+import type { ErrorComponentProps } from "@tanstack/react-router"
+
+export function DefaultCatchBoundary({ error }: ErrorComponentProps) {
+  const router = useRouter()
+  const isRoot = useMatch({
+    strict: false,
+    select: (state) => state.id === rootRouteId,
+  })
+
+  console.error(`DefaultCatchBoundary Error:`, error)
+
+  return (
+    <div className="min-w-0 flex-1 p-4 flex flex-col items-center justify-center gap-6">
+      <ErrorComponent error={error} />
+      <div className="flex gap-2 items-center flex-wrap">
+        <button
+          onClick={() => {
+            router.invalidate()
+          }}
+          className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
+        >
+          Try Again
+        </button>
+        {isRoot ? (
+          <Link
+            to="/"
+            className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
+          >
+            Home
+          </Link>
+        ) : (
+          <Link
+            to="/"
+            className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
+            onClick={(e) => {
+              e.preventDefault()
+              window.history.back()
+            }}
+          >
+            Go Back
+          </Link>
+        )}
+      </div>
+    </div>
+  )
+}

examples/react/offline-transactions/src/components/NotFound.tsx

@@ -0,0 +1,25 @@
+import { Link } from "@tanstack/react-router"
+
+export function NotFound({ children }: { children?: any }) {
+  return (
+    <div className="space-y-2 p-2">
+      <div className="text-gray-600 dark:text-gray-400">
+        {children || <p>The page you are looking for does not exist.</p>}
+      </div>
+      <p className="flex items-center gap-2 flex-wrap">
+        <button
+          onClick={() => window.history.back()}
+          className="bg-emerald-500 text-white px-2 py-1 rounded uppercase font-black text-sm"
+        >
+          Go back
+        </button>
+        <Link
+          to="/"
+          className="bg-cyan-600 text-white px-2 py-1 rounded uppercase font-black text-sm"
+        >
+          Start Over
+        </Link>
+      </p>
+    </div>
+  )
+}