feature(docs): improve logic for asset origin fix (tldraw#8768)

### Problem

Docs and marketing are two separate Next apps on Vercel. When marketing
rewrites a path (e.g. `tldraw.dev/quick-start`) and returns docs HTML,
the browser’s address bar is still the marketing origin, but the HTML
referenced `/_next/static/...` as root-relative paths. Those requests
went to marketing’s `/_next` (wrong app / wrong hashes) instead of docs’
`/_next`.

Setting `ASSET_PREFIX` only in some environments (or only on Production)
was easy to get wrong: Preview builds often had no prefix, and
Production could pin the wrong hostname (e.g. a `*.vercel.app` alias)
while the live site was `tldraw.dev`, which caused 404s, cache skew (old
HTML vs new static files), and confusion.

### What we changed

`assetPrefix` (and the same base for `assetUrl()` on `public/` paths)
now resolves to:

1. `ASSET_PREFIX` when set (explicit override), else
2. `https://${VERCEL_URL}` on Vercel (the current deployment URL), else
3. unset locally → root-relative assets as before.

### Why it helps

- Every Vercel build automatically points JS/CSS (and prefixed `public/`
URLs) at that deployment’s static host, without maintaining
Preview-specific `ASSET_PREFIX` for every branch.
- `ASSET_PREFIX` remains an escape hatch when you need a fixed canonical
origin (e.g. force the apex in prod).
- Docs HTML served through rewrites still loads `/_next` from the docs
deployment that produced the page, which removes the “wrong `/_next`
host” class of bugs.

### Change type

- [ ] `bugfix`
- [x] `improvement`
- [ ] `feature`
- [ ] `api`
- [ ] `other`

Author: kaneel

apps/docs/next.config.js

@@ -3,9 +3,19 @@
 // Configurable domain for rewrites
 const REWRITE_DOMAIN = 'tldrawdotdev.framer.website'
 
+function resolveAssetOrigin() {
+	const explicit = process.env.ASSET_PREFIX?.trim()
+	if (explicit) return explicit.replace(/\/$/, '')
+
+	const vercelUrl = process.env.VERCEL_URL?.trim()
+	if (vercelUrl) return `https://${vercelUrl}`
+
+	return undefined
+}
+
 const nextConfig = {
 	reactStrictMode: true,
-	assetPrefix: process.env.ASSET_PREFIX || undefined,
+	assetPrefix: resolveAssetOrigin(),
 	experimental: {
 		scrollRestoration: true,
 	},

apps/docs/utils/asset-url.test.ts

@@ -3,53 +3,96 @@ import { assetUrl } from './asset-url'
 
 describe('assetUrl', () => {
 	it('returns the original path when ASSET_PREFIX is unset', () => {
-		const prev = process.env.ASSET_PREFIX
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
 		try {
 			delete process.env.ASSET_PREFIX
+			delete process.env.VERCEL_URL
 			expect(assetUrl('/favicon.svg')).toBe('/favicon.svg')
 		} finally {
-			process.env.ASSET_PREFIX = prev
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
 		}
 	})
 
 	it('returns the original path when ASSET_PREFIX is empty/whitespace', () => {
-		const prev = process.env.ASSET_PREFIX
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
 		try {
 			process.env.ASSET_PREFIX = '   '
+			delete process.env.VERCEL_URL
 			expect(assetUrl('/favicon.svg')).toBe('/favicon.svg')
 		} finally {
-			process.env.ASSET_PREFIX = prev
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
 		}
 	})
 
 	it('prefixes root-relative paths', () => {
-		const prev = process.env.ASSET_PREFIX
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
 		try {
 			process.env.ASSET_PREFIX = 'https://docs.example.com'
+			delete process.env.VERCEL_URL
 			expect(assetUrl('/images/foo.png')).toBe('https://docs.example.com/images/foo.png')
 		} finally {
-			process.env.ASSET_PREFIX = prev
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
 		}
 	})
 
 	it('strips a trailing slash from the prefix', () => {
-		const prev = process.env.ASSET_PREFIX
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
 		try {
 			process.env.ASSET_PREFIX = 'https://docs.example.com/'
+			delete process.env.VERCEL_URL
 			expect(assetUrl('/images/foo.png')).toBe('https://docs.example.com/images/foo.png')
 		} finally {
-			process.env.ASSET_PREFIX = prev
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
+		}
+	})
+
+	it('uses VERCEL_URL when ASSET_PREFIX is unset', () => {
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
+		try {
+			delete process.env.ASSET_PREFIX
+			process.env.VERCEL_URL = 'tldraw-docs-abc123.vercel.app'
+			expect(assetUrl('/images/foo.png')).toBe(
+				'https://tldraw-docs-abc123.vercel.app/images/foo.png'
+			)
+		} finally {
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
+		}
+	})
+
+	it('prefers ASSET_PREFIX over VERCEL_URL', () => {
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
+		try {
+			process.env.ASSET_PREFIX = 'https://explicit.example.com'
+			process.env.VERCEL_URL = 'tldraw-docs-abc123.vercel.app'
+			expect(assetUrl('/favicon.svg')).toBe('https://explicit.example.com/favicon.svg')
+		} finally {
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
 		}
 	})
 
 	it('does not change non-root-relative paths', () => {
-		const prev = process.env.ASSET_PREFIX
+		const prevPrefix = process.env.ASSET_PREFIX
+		const prevVercel = process.env.VERCEL_URL
 		try {
 			process.env.ASSET_PREFIX = 'https://docs.example.com'
+			delete process.env.VERCEL_URL
 			expect(assetUrl('https://cdn.example.com/a.png')).toBe('https://cdn.example.com/a.png')
 			expect(assetUrl('relative.png')).toBe('relative.png')
 		} finally {
-			process.env.ASSET_PREFIX = prev
+			process.env.ASSET_PREFIX = prevPrefix
+			process.env.VERCEL_URL = prevVercel
 		}
 	})
 })

apps/docs/utils/asset-url.ts

@@ -1,6 +1,16 @@
+function resolveAssetOrigin(): string | undefined {
+	const explicit = process.env.ASSET_PREFIX?.trim()
+	if (explicit) return explicit.replace(/\/$/, '')
+
+	const vercelUrl = process.env.VERCEL_URL?.trim()
+	if (vercelUrl) return `https://${vercelUrl}`
+
+	return undefined
+}
+
 export function assetUrl(path: string): string {
 	if (!path.startsWith('/')) return path
-	const prefix = process.env.ASSET_PREFIX?.trim()
-	if (!prefix) return path
-	return `${prefix.replace(/\/$/, '')}${path}`
+	const origin = resolveAssetOrigin()
+	if (!origin) return path
+	return `${origin}${path}`
 }