Update project documentation

DEVELOPERS.md

@@ -175,7 +175,22 @@ We review PRs in the order of their submission. We try to accept the earliest on
 
 ### Add a redirect
 
-Create a new entry in the [`redirects.js`](https://github.com/supabase/supabase/blob/master/apps/www/lib/redirects.js) file in our main site.
+Supabase.com uses two complementary redirect systems:
+
+**For static, 1-to-1 redirects** (simple `/old → /new` mappings):
+
+- Add to [`apps/www/lib/bulk-redirects/`](https://github.com/supabase/supabase/tree/master/apps/www/lib/bulk-redirects)
+- Served by Vercel's edge layer via `vercel.json`
+- Fast and low-overhead
+- See [`apps/www/lib/bulk-redirects/README.md`](https://github.com/supabase/supabase/blob/master/apps/www/lib/bulk-redirects/README.md) for examples and structure
+
+**For dynamic, pattern-based redirects** (path variables, conditional logic):
+
+- Create a new entry in [`apps/www/lib/redirects.js`](https://github.com/supabase/supabase/blob/master/apps/www/lib/redirects.js)
+- Handled by Next.js's `redirects()` function
+- Use when static 1-to-1 mapping isn't sufficient (e.g., paths with `:path*`, `:slug`, regex patterns)
+
+**Decision rule:** If your redirect has no variables or complex matching, use bulk redirects. Otherwise, use `lib/redirects.js`.
 
 ---
 

apps/www/README.md

@@ -33,6 +33,24 @@ generators, a stub compiler, and a fake AWS CLI.
 - **Compress images**: All new images should be compressed before committing. Use tools like Clop or ImageOptim to reduce file size without noticeable quality loss.
 - **Image locations**: Store blog post images in `apps/www/public/images/blog/`. Event images go in `apps/www/public/images/events/`. Customer logos go in `apps/www/public/images/customers/logos/on-light/` and `on-dark/` (see Customer Stories below).
 
+### Redirects
+
+Supabase.com uses two complementary redirect systems depending on the redirect type:
+
+**Static, 1-to-1 redirects** → `apps/www/lib/bulk-redirects/` (Vercel edge layer via `vercel.json`)
+
+- Simple fixed-path-to-path mappings (e.g., `/docs/guides/old-page` → `/docs/guides/new-page`)
+- Fast, low-overhead
+- See `apps/www/lib/bulk-redirects/README.md` for details
+
+**Dynamic, pattern-based redirects** → `apps/www/lib/redirects.js` (Next.js `redirects()` function)
+
+- Path variables and pattern matching (e.g., `/images/customers/logos/:slug*`)
+- Conditional logic
+- Used when static 1-to-1 mapping isn't sufficient
+
+See the bulk redirects README for decision guidance: if your redirect has no variables or complex matching, use bulk redirects. Otherwise, use `lib/redirects.js`.
+
 ### OG image generation
 
 Open Graph (OG) images for social sharing are handled differently across content types:

apps/www/lib/bulk-redirects/README.md

@@ -10,7 +10,33 @@ Static redirects served by Vercel's edge layer via `vercel.json`'s `bulkRedirect
   - References (`/docs/reference/*`)
   - Legacy paths (`/docs/library/*`, etc.)
 
-## Adding Redirects
+## When to use bulk redirects vs. dynamic redirects
+
+Choose **bulk redirects** for **static, 1-to-1 mapped redirects** — simple `/old → /new` mappings with no path matching logic.
+
+Choose **dynamic redirects** (in `lib/redirects.js`) for **pattern-based or conditional redirects** — paths with variables, broader pattern matching, or conditional logic.
+
+### Bulk redirects (this folder)
+
+✅ **Use for:** Static, fixed-path-to-path mappings
+
+- `/docs/guides/old-page` → `/docs/guides/new-page`
+- `/blog/old-post` → `/blog/new-post`
+
+❌ **Don't use for:**
+
+- Path patterns with variables (`:path*`, `:match*`, etc.)
+- Regex patterns
+- Conditional redirects
+
+### Dynamic redirects (`lib/redirects.js`)
+
+✅ **Use for:** Pattern matching and conditional logic
+
+- `/images/customers/logos/light/:path*` → `/images/customers/logos/on-dark/:path*`
+- `/images/customers/logos/:slug(?)` → `/images/customers/logos/on-light/:slug.png`
+
+## Adding static redirects
 
 Add static redirects (simple `/old → /new` mappings with **no** `:path*`, `:match*`, or regex patterns) to the appropriate file. Vercel reads all `.json` files from this folder and serves them at the edge.
 
@@ -30,10 +56,6 @@ pnpm run generate:docs-redirects-md-variants
 
 CI fails the build if this file is out of sync with `docs.json` (see `.github/workflows/www-tests.yml`).
 
-## Dynamic Redirects
-
-Redirects with path matching patterns (`:path*`, `:match*`, regex) stay in `lib/redirects.js` and are handled by Next.js's `redirects()` function.
-
 ## Deployment
 
 Vercel reads all `.json` files from this folder (via `vercel.json`'s `bulkRedirectsPath`) and serves them at the edge. There's no build-time generation step — `docs-redirects-md-variants.json` is committed directly, like `docs.json` and `blog.json`.