From 03e34fbb8b6dc747d1de127d1c6892ae2876fa65 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Wed, 21 Aug 2024 07:15:18 -0600
Subject: [PATCH] docs: Add guide for local-development that explains
 work-around for http/1.1 issues (#1545)

Several people have hit this so let's document the fix
---
 docs/.vitepress/config.mts       |  3 +-
 docs/guides/local-development.md | 48 ++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/local-development.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 5a75d670c0..65dd637d78 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -49,7 +49,8 @@ export default defineConfig({
           { text: 'Shapes', link: '/guides/shapes' },
           // { text: 'Deployment', link: '/guides/deployment' },
           // { text: 'Writing clients', link: '/guides/write-your-own-client' },
-          { text: 'Telemetry', link: '/guides/telemetry' }
+          { text: 'Telemetry', link: '/guides/telemetry' },
+          { text: 'Local Development', link: '/guides/local-development' }
         ]
       },
       {
diff --git a/docs/guides/local-development.md b/docs/guides/local-development.md
new file mode 100644
index 0000000000..2a9509fcad
--- /dev/null
+++ b/docs/guides/local-development.md
@@ -0,0 +1,48 @@
+---
+outline: deep
+---
+
+# Local Development
+
+## Why are my shapes loading so slow in the browser?
+
+The most frequent issue people encounter with local development with Electric
+is a mysterious slow-down when your web app is subscribed to 6+ shapes.
+
+This slow-down is due to a limitation of the legacy version of HTTP, 1.1.
+Browsers only allow 6 simultaneous requests to a specific backend as each
+HTTP/1.1 request uses its own expensive TCP connection. As shapes are loaded over HTTP,
+this means only 6 shapes can be getting updates with HTTP/1.1 due to the this
+browser restriction. All other requests pause until there's an opening.
+
+HTTP/2, introduced in 2015, fixes this problem by _multiplexing_ each request
+to a server over the same TCP connection. This allows essentially unlimited
+connections.
+
+HTTP/2 is standard across the vast majority of hosts now. Unfortunately it's
+not yet standard in local dev environments.
+
+To fix this, we'll setup a local reverse-proxy using the very popular [Caddy
+server](https://caddyserver.com/).
+
+It automatically sets up HTTP/2 and proxies requests back to Electric getting around
+the 6 requests HTTP/1.1 limitation in the browser.
+
+### Run Caddy
+This command runs Caddy so it's listening on port 3001 and proxying shape
+requests to Electric which listens on port 3000. If you're loading shapes
+through your API or framework dev server, replaces 3000 with the port your API
+or dev server is listening on.
+
+```cli
+npx @radically-straightforward/caddy run --config - --adapter caddyfile <<EOF
+:3001 {
+  reverse_proxy localhost:3000
+  encode {
+    gzip
+  }
+}
+EOF
+```
+
+Now change your shape URLs to use port 3001 instead of port 3000 and you're done!