[benitav]

Stacked on #730. This PR gives each page that touches the write path one job, so new users follow one path from setup to a working write API instead of jumping between pages that repeat each other.

Reference: https://journeyapps.slack.com/archives/C0BA0HHLBQ9/p1793358584508909?thread_ts=1793189532.594099&cid=C0BA0HHLBQ9

Important (contentious?) decisions:

• CloudCode docs were removed (still available via direct link, but nothing mentions them anymore)
• To get started, the main entry point is "Choosing Your Implementation" - whenever we mention the upload path, e.g. from the setup guide, we explain it briefly and then link users there to continue. As opposed to e.g. the Write path overview page - which just explains things.

How the Pages Fit Together

Onboarding path

1. Setup guide or SDK reference: reads come first. The upload step explains the model in one sentence and links once, to Choosing Your Implementation.
2. Choosing Your Implementation: a table that picks the route guide for your setup.
3. Route guide (Existing API, Supabase PostgREST, Supabase Edge Function, reference write implementation, Build Your Own): how to set up that route, and how it handles failed writes.

Integration and migration guides (Supabase, Neon, Atlas Device Sync, Electric) link straight to the route guide that fits them.

Detail pages, one job each

• Write Path Overview: the mental model, enough to implement. It ends with "Choose Where to Start".

• Write Path Concepts: the rules every write API follows: operations, authentication, applying writes before responding, failures and rollback. It opens with a short orientation, so it also works as an entry point.

• Client-Side Integration: what the SDK does: when it calls fetchCredentials() and uploadData(), throttling, retries, and stalled-queue detection.

• App Backend Setup: the two jobs your backend does for PowerSync: It also lists the kinds of backend you can use: your existing backend, the reference write implementation, a custom backend, Supabase or Neon, serverless functions, or a data API service.

• Everything else (Writing Data, Usage Examples, Consistency, the conflict and checkpoint pages) covers its own topic and links to Concepts instead of explaining the flow again.

Changes

• Removed repetition: at least six pages explained the write flow again. Now only the Overview (simple) and Concepts (detailed) explain it, and other pages give a sentence and a link.
• One operation table: it's in Concepts. The other copies also disagreed about what PUT contains.
• Reads first in onboarding: the setup guide and SDK references focus on reading data. Their placeholder upload code is consistent, and the setup guide says what it does.
• One next step for uploads: SDK references, code comments, the setup guide, Usage Examples and Writing Data all send readers to Choosing Your Implementation. Previously they went through Usage Examples and the Dashboard's connector generator.
• Fixed failure handling in examples and guidance:
  • Next.js and Nuxt no longer discard writes on any error.
  • The .NET reference is now a stub; it used to block the queue on every 4xx.
  • Usage Examples and Custom Conflict Resolution complete permanent rejections and retry temporary failures. The conflict-resolution example also sends the fields its backend expects and passes the database transaction connection to its helpers.
  • The "must return 2xx" rule that contradicted Concepts is gone.
• Fixed wrong, circular and dead-end links:
  • The Capacitor tip, auth overview, FAQ and Electric guide links are fixed.
  • Client-Side Integration's Example Implementation now links to the reference implementation instead of SDK stubs that linked back.
  • New links to Custom Write Checkpoints and Blocked Transactions where readers had no way forward.
• CloudCode hidden: the page is out of the sidebar and still reachable at its URL. No other page mentions it, and the Atlas guide points MongoDB users to the reference write implementation instead.

Not in this PR: the "writes → mutations" terminology pass

AI disclosure: I used Claude Code (Opus 5.5) to find issues in the current flow and content and come up with a better structure and fix inaccuracies. Claude Code made all changes and also drafted this description, I guided, reviewed and tweaked each change on a high level. Codex (6.1 Sol Extra High) reviewed this PR for accuracy.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
powersync	🟢 Ready	View Preview	Nov 3, 2026, 1:25 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

The option that populates previousValues is called trackPrevious in the JS/web SDK (not trackPreviousValues, which is the name used in the other SDKs). Since this page's examples are JS-only, the comment should read (trackPrevious) to match what a reader would actually set on their Table definition.

Suggested change

	previousValues?: Record<string, any>; // Previous values (trackPreviousValues)
	previousValues?: Record<string, any>; // Previous values (trackPrevious)

[claude]

"Upload the queue through the backend API" is awkward: you don't upload a queue itself, you upload the mutations it holds. Consider rewording, e.g. "To upload queued changes through the backend API you already have, see Use Your Existing API."