@specific.dev/cli 0.1.102 → 0.1.104

package/dist/docs/sync.md

@@ -46,6 +46,44 @@ For implementation details, see the Electric documentation:
 - Authentication and proxying: https://electric-sql.com/docs/guides/auth
 - Shapes and client usage: https://electric-sql.com/docs/guides/shapes
 - Handling writes: https://electric-sql.com/docs/guides/writes
+- Troubleshooting: https://electric-sql.com/docs/guides/troubleshooting
+
+## Proxy configuration
+
+When proxying Electric requests from your backend, you must handle headers and query parameters correctly. Getting these wrong causes silent failures — browsers block responses or serve stale cached data without clear error messages.
+
+### Expose Electric response headers
+
+Electric returns custom headers that the client SDK needs (`electric-handle`, `electric-offset`, `electric-schema`). Browsers block JavaScript from reading non-standard response headers unless they are listed in `Access-Control-Expose-Headers`:
+
+```
+Access-Control-Expose-Headers: electric-handle, electric-offset, electric-schema
+```
+
+### Strip upstream headers
+
+Electric's response includes its own CORS and caching headers. If your proxy copies these through and your CORS middleware also adds its own, the browser receives duplicate `Access-Control-Allow-Origin` values and rejects the response. Before setting your own headers, strip these from Electric's response:
+
+- `Access-Control-Allow-Origin` and other `Access-Control-*` headers
+- `Content-Encoding` and `Content-Length` (fetch decompresses the body but doesn't update these headers, which breaks browser decoding)
+- `Cache-Control` (see below)
+
+### Override caching
+
+Electric returns `Cache-Control` with `max-age` and `stale-age` for request collapsing at CDN level. During development, this can cause browsers to serve stale cached responses — for example, responses cached before CORS headers were configured correctly will keep failing even after the proxy is fixed. Override with `Cache-Control: no-store` on your proxy response to prevent this.
+
+### Control query parameters
+
+Set these server-side — never pass them through from the client:
+
+- `table` — letting clients specify the table allows access to any table
+- `where` — this is your authorization filter
+- `columns` — clients could request sensitive columns
+- `secret` — never expose the API secret to clients
+
+Only forward Electric protocol parameters from the client:
+
+- `offset`, `handle`, `live`, `live_sse`, `replica`, `log`
 
 ## Using the Electric TypeScript SDK
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.102",
+  "version": "0.1.104",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",