fix examples handling of response headers

[KyleAMathews]

Summary

Simplify proxy examples to forward all response headers from Electric instead of selectively managing individual headers. This fixes MissingHeadersError that users hit when proxies strip Electric's CORS headers.

Root Cause

Users running Electric behind a proxy were getting MissingHeadersError because the example proxy code was selectively copying headers — either missing newly added Electric headers or stripping CORS headers like access-control-expose-headers. The yjs example had an additional subtle bug: it manually copied headers into a new Response while also hardcoding a list of electric-* headers, creating a maintenance burden every time Electric added a new header.

Approach

Instead of maintaining an explicit list of headers to forward, the proxies now pass through all response headers from Electric, only removing content-encoding and content-length (which become invalid when fetch() decompresses the body).

Key changes:

• tanstack proxy: Removed CORS header filtering — Electric already sets correct CORS headers including access-control-expose-headers
• yjs proxy: Replaced ~30 lines of manual header copying with a simple new Response() using a mutable copy of the upstream headers. Always constructs a new Response (not just in the content-encoding branch) because Node.js fetch() returns immutable headers that Hono's CORS middleware can't merge into
• Error message: Improved MissingHeadersError to give actionable guidance about forwarding all headers, specifically mentioning access-control-expose-headers
• Troubleshooting docs: Updated to match the new "forward everything" guidance

Key Invariants

• Proxies must return a Response with mutable headers so framework middleware (e.g., Hono CORS) can add its own headers
• Only content-encoding and content-length should be stripped, and only when the proxy decompresses the body
• Electric's own access-control-expose-headers header must reach the browser for the client to read electric-* headers

Non-goals

• Did not change the tanstack proxy's CORS_HEADERS constant, which is still used for non-proxy responses (health, POST/DELETE, errors)

Verification

Review the example proxy code to confirm all Electric headers pass through:

# Check the proxy examples work with Electric
cd examples/tanstack && pnpm dev
cd examples/yjs && pnpm dev

Files changed

File	Change
examples/tanstack/src/server/app.js	Stop filtering CORS headers from Electric responses, forward all headers
examples/yjs/src/server/server.ts	Remove exposeHeaders CORS config and manual header copying, always create mutable Response
packages/typescript-client/src/error.ts	Improve MissingHeadersError with actionable proxy guidance
website/docs/guides/troubleshooting.md	Update "missing headers" solution to recommend forwarding all headers

---

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	20e4575
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/698b69a515f9f50008a03ca7
😎 Deploy Preview	https://deploy-preview-3825--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.68%. Comparing base (f9b25d6) to head (20e4575).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3825   +/-   ##
=======================================
  Coverage   87.68%   87.68%           
=======================================
  Files          23       23           
  Lines        2078     2078           
  Branches      547      549    +2     
=======================================
  Hits         1822     1822           
  Misses        254      254           
  Partials        2        2           

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	93.64% <100.00%> (ø)
packages/y-electric	56.05% <ø> (ø)
typescript	87.68% <100.00%> (ø)
unit-tests	87.68% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@electric-sql/react@3825

npm i https://pkg.pr.new/@electric-sql/client@3825

npm i https://pkg.pr.new/@electric-sql/y-electric@3825

commit: 20e4575

[plutou-ben]

@balegas - Is this related to my error? If so, will I need to update anything on how the electric_query_params?

[balegas]

@balegas - Is this related to my error? If so, will I need to update anything on how the electric_query_params?

No, just consolidating examples.