Routing & Custom Domains

static.bio supports two URL models: static.bio/{username} and custom subdomains like links.janedoe.com. Routing is optimized for minimal latency.

URL Model

Default URLs

Every profile gets a default URL:

https://static.bio/{username}

Username format: alphanumeric + hyphens/underscores, 1-50 characters. Examples:jane-doe, alice_smith, bob123.

Custom Domains

Lifetime plan users can configure custom subdomains:

https://links.janedoe.com
https://bio.company.com
https://me.example.org

Custom domains point to the same profile but use the user's own domain.

Routing Strategy

Fast Path for Usernames

The proxy (proxy.ts) uses a fast path for username routes:

  • Reserved paths (dashboard, api, docs, etc.) skip profile lookup
  • Valid usernames (regex pattern) are rewritten directly to /api/profile/{username}
  • No database lookup needed for default URLs—username is extracted from path

Custom Domain Lookup

For custom domains, the proxy:

  • Reads Host header from request
  • Looks up hostname → profileId in database (or cache)
  • Rewrites to /api/profile/{username} using the resolved username

Custom domain resolution is cached to minimize database queries. The mapping is stored in the CustomDomain table with indexes on hostname for fast lookups.

Rewrite vs Redirect

We use rewrite (not redirect) to minimize round-trips:

  • Rewrite: Server internally routes to /api/profile/{username} without changing URL
  • Redirect: Would send 302/301, requiring client to make second request

Rewrites save ~50-100ms by eliminating the redirect round-trip. The browser sees the original URL, but the server serves content from the API route.

Custom Domains Implementation

Domain Mapping

Custom domains are stored in the database:

CREATE TABLE "CustomDomain" (
  id TEXT PRIMARY KEY,
  "profileId" TEXT NOT NULL REFERENCES "Profile"(id),
  hostname TEXT NOT NULL UNIQUE,
  verified BOOLEAN DEFAULT false,
  "createdAt" TIMESTAMP DEFAULT NOW(),
  "updatedAt" TIMESTAMP DEFAULT NOW()
);

CREATE INDEX "CustomDomain_hostname_idx" ON "CustomDomain"(hostname);

The hostname index ensures O(log n) lookup time for domain resolution.

Vercel Integration

Custom domains are automatically added to Vercel via API:

  • When a user adds a custom domain in the dashboard, we call Vercel's API to add it to the project
  • When a domain is removed, we call Vercel's API to remove it
  • DNS configuration is handled by the user (CNAME record pointing to Vercel)

This integration is optional—if Vercel API credentials aren't configured, users can manually add domains in Vercel's dashboard.

Scalability

The routing system is designed to scale:

  • Many custom domains: Database lookup is indexed and cached
  • Fast username routes: No database lookup needed—username extracted from path
  • Edge caching: Future enhancement: cache domain → username mappings at edge

Current implementation supports thousands of custom domains with minimal latency impact. Future optimizations could add edge-level caching for even faster resolution.