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

.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/README.otel.md

@@ -0,0 +1,102 @@
+# OpenTelemetry Setup
+
+This example includes OpenTelemetry instrumentation for observability of offline transactions.
+
+## Quick Start
+
+### 1. Set up Honeycomb API Key
+
+```bash
+cp .env.example .env
+# Edit .env and add your Honeycomb API key
+```
+
+Get your API key from https://ui.honeycomb.io/account
+
+### 2. Start the OpenTelemetry Collector
+
+```bash
+docker-compose up -d
+```
+
+This starts the OpenTelemetry Collector with CORS support on port 4318.
+
+### 3. Enable Tracing in the App
+
+Uncomment the tracing configuration in `src/routes/indexeddb.tsx` or `src/routes/localstorage.tsx`:
+
+```typescript
+const offlineExecutor = createIndexedDBOfflineExecutor({
+  endpoint: "http://localhost:4318/v1/traces",
+})
+```
+
+### 4. View Traces in Honeycomb
+
+1. Go to https://ui.honeycomb.io
+2. Navigate to your environment
+3. You should see traces from `@tanstack/offline-transactions-example`
+
+## What Gets Traced
+
+The offline transactions package instruments:
+
+- **Transaction execution**: Full lifecycle from persistence to completion
+- **Outbox operations**: add, get, update, remove transactions
+- **Retry logic**: Failed transactions with retry attempts and delays
+- **Error handling**: Failed spans with error details and stack traces
+- **Scheduler operations**: Transaction queuing and batching
+
+## Configuration Options
+
+### Using Jaeger (Local Development)
+
+If you prefer Jaeger for local development:
+
+1. Uncomment the `jaeger` service in `docker-compose.yml`
+2. Update `otel-collector-config.yaml` to use the Jaeger exporter
+3. Access Jaeger UI at http://localhost:16686
+
+### Custom Honeycomb Configuration
+
+You can pass headers for Honeycomb configuration:
+
+```typescript
+const offlineExecutor = createIndexedDBOfflineExecutor({
+  endpoint: "http://localhost:4318/v1/traces",
+  headers: {
+    // Optional: specify dataset
+    "x-honeycomb-dataset": "my-dataset",
+  },
+})
+```
+
+## Troubleshooting
+
+### CORS Errors
+
+If you see CORS errors, verify:
+
+- The collector is running: `docker-compose ps`
+- Port 4318 is accessible: `curl http://localhost:4318`
+- The `allowed_origins` in `otel-collector-config.yaml` matches your app's origin
+
+### No Traces Appearing
+
+Check collector logs:
+
+```bash
+docker-compose logs otel-collector
+```
+
+Verify your Honeycomb API key is correct:
+
+```bash
+docker-compose exec otel-collector env | grep HONEYCOMB
+```
+
+### Stopping the Collector
+
+```bash
+docker-compose down
+```

examples/react/offline-transactions/docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  # OpenTelemetry Collector - handles CORS and forwards traces to Honeycomb
+  otel-collector:
+    image: otel/opentelemetry-collector:latest
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    environment:
+      # Set your Honeycomb API key here or via .env file
+      - HONEYCOMB_API_KEY=${HONEYCOMB_API_KEY}
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
+    ports:
+      - "4318:4318" # OTLP HTTP endpoint with CORS support
+    restart: unless-stopped
+
+  # Optional: Local Jaeger for development
+  # Uncomment this and update otel-collector-config.yaml to use Jaeger instead
+  # jaeger:
+  #   image: jaegertracing/all-in-one:latest
+  #   environment:
+  #     - COLLECTOR_OTLP_ENABLED=true
+  #   ports:
+  #     - "16686:16686"  # Jaeger UI
+  #     - "4317:4317"    # OTLP gRPC
+  #   restart: unless-stopped

examples/react/offline-transactions/otel-collector-config.yaml

@@ -0,0 +1,35 @@
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+        cors:
+          allowed_origins:
+            - "http://localhost:*"
+            - "http://127.0.0.1:*"
+          allowed_headers:
+            - "*"
+          max_age: 7200
+
+exporters:
+  # Honeycomb exporter
+  otlp/honeycomb:
+    endpoint: api.honeycomb.io:443
+    headers:
+      x-honeycomb-team: "${HONEYCOMB_API_KEY}"
+
+  # Jaeger exporter (optional - uncomment to use local Jaeger instead)
+  # otlp/jaeger:
+  #   endpoint: jaeger:4317
+  #   tls:
+  #     insecure: true
+
+  # Debug exporter for troubleshooting
+  debug:
+    verbosity: detailed
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [otlp/honeycomb, debug]

examples/react/offline-transactions/package.json

@@ -0,0 +1,44 @@
+{
+  "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": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.56.0",
+    "@opentelemetry/instrumentation": "^0.56.0",
+    "@opentelemetry/instrumentation-fetch": "^0.56.0",
+    "@opentelemetry/resources": "^1.29.0",
+    "@opentelemetry/sdk-trace-web": "^1.29.0",
+    "@opentelemetry/semantic-conventions": "^1.29.0",
+    "@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"
+}