Configuration

Linkbeam is configured through wrangler.jsonc for infrastructure bindings and Wrangler secrets for credentials. Vars are non-secret defaults you can commit.

Cloudflare bindings

Binding Type Purpose
DB D1 Artists, tracks, links, destinations, metrics, settings
LINK_CACHE KV Published smartlink JSON cache (~60s TTL)
ARTWORK R2 Owned artwork storage
CONVERSION_EVENTS Queue Async Meta CAPI delivery (DLQ on failure)
ANALYTICS Analytics Engine Optional raw event points (commented out by default)

Public vars

Variable Default Notes
WORKER_NAME linkbeam Prefix for D1/R2/queue resource names in onboarding snippets
PUBLIC_BASE_URL "" Set to your deployed host (e.g. https://links.example.com). Empty uses request origin.
META_API_VERSION v23.0 Meta Graph API version for CAPI
META_CONVERSION_VALUE 1 Relative value sent with conversion events (not literal revenue)
META_CURRENCY USD Currency code for conversion value
META_TEST_EVENT_CODE "" Optional Test Events code from Meta Events Manager
SUBSCRIBER_RETENTION_DAYS 365 Scheduled retention window for consented email signups (1–3650 days)

Secrets

Set with wrangler secret put NAME or .dev.vars locally (never commit).

Secret Required Purpose
META_PIXEL_ID For tracking Meta Pixel ID
META_ACCESS_TOKEN For CAPI Conversions API access token. Store only with wrangler secret put META_ACCESS_TOKEN; Linkbeam never persists it in D1.
SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET Optional Full Spotify import with ISRC
CF_ACCESS_TEAM_DOMAIN / CF_ACCESS_AUD Optional Cloudflare Access JWT for /admin
ADMIN_PASSWORD_HASH / ADMIN_SESSION_SECRET Optional Password gate for /admin when Access is not used. Generate the PBKDF2 record with bun run auth:hash.
RATE_LIMIT_SECRET Required for email signups HMAC key for privacy-safe per-client signup limits. Generate a random 32-byte value and store it only as a Worker secret.

Routes

Route Handler
/ Marketing landing (on your Worker)
/:slug Public smartlink fan page
/out/:slug/:platform Outbound click redirect + tracking
/d/:slug/:platform Short outbound alias (same behavior)
/admin/* Operator UI (auth required in production)
/api/* REST endpoints (import, subscribe, admin APIs)
/artwork/:trackId Artwork proxy from R2

Custom domain

Replace workers_dev: true with a route block:

"routes": [
  {
    "pattern": "links.example.com",
    "custom_domain": true
  }
]

Set PUBLIC_BASE_URL to the same host so outbound links and CAPI payloads use the correct origin.

Scheduled tasks

A cron trigger runs every 15 minutes to retry failed CAPI events logged in D1. Configured in wrangler.jsonc under triggers.crons.