Velt Proxy Server

Deploy a reverse proxy in front of the Velt SDK's backend services and optional CDN bundle delivery. Pick Cloudflare Workers (managed, ~15 min) or nginx (self-hosted, ~45 min). Each platform folder has runnable code and a step-by-step README.

Why run a proxy?

• Egress control — route all Velt SDK backend traffic through infrastructure you own and monitor.
• Compliance — keep third-party endpoints off your app's public egress rules.
• Custom domains — serve backend traffic from subdomains under your own brand.
• Geo-routing — place the proxy closer to your users than the nearest upstream region.

Architecture

┌─────────┐     ┌────────────────────────┐     ┌──────────────────────┐
│ Browser │ ──▶ │  your proxy domains:   │ ──▶ │ Upstream (Google /   │
│ (Velt   │     │   auth-proxy.*         │     │  Velt)               │
│  SDK)   │     │   v2db-proxy.*         │     │                      │
│         │     │   v1db-proxy.*         │     │                      │
│         │     │   storage-proxy.*      │     │                      │
│         │     │   cdn-proxy.*          │     │                      │
│         │     │   api-proxy.*          │     │                      │
└─────────┘     └────────────────────────┘     └──────────────────────┘
                    (Cloudflare / nginx)

You deploy up to six proxy endpoints under subdomains you control — one per proxyConfig host field you want to use — and configure the Velt SDK to route through them.

Services covered

Service	Routing notes
Auth	Path-based: /v1/token → token-refresh upstream, else → identity upstream
v2Db	Straight passthrough
v1Db	Dynamic upstream host from ?ns= query param. WebSocket upgrade required.
Storage	Straight passthrough
CDN	/lib/* passthrough to cdn.velt.dev (SDK bundle delivery)
API	Straight passthrough to api.velt.dev (Velt cloud functions)

Pick your platform

Platform	Best for	Setup time	Link
Cloudflare Workers	Edge-distributed, zero infra, fastest to ship	~15 min	cloudflare/README.md
nginx	Self-hosted, full control, existing nginx infrastructure	~45 min	nginx/README.md

Velt SDK configuration

After your proxy is deployed and verified, configure the Velt SDK to route through it. Replace customer.com with your actual domain.

Non-React (@veltdev/client) — verified with Velt SDK v5.0.2-beta.15:

import { initVelt } from '@veltdev/client';

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    v2DbHost:    'v2db-proxy.customer.com',
    v1DbHost:    'v1db-proxy.customer.com',
    storageHost: 'storage-proxy.customer.com',
    authHost:    'auth-proxy.customer.com',
    cdnHost:     'cdn-proxy.customer.com',
    apiHost:     'api-proxy.customer.com',
    forceLongPolling: false, // optional, default false
  },
});

React (@veltdev/react):

import { VeltProvider } from '@veltdev/react';

<VeltProvider apiKey="YOUR_API_KEY" config={{
  proxyConfig: {
    v2DbHost:    'v2db-proxy.customer.com',
    v1DbHost:    'v1db-proxy.customer.com',
    storageHost: 'storage-proxy.customer.com',
    authHost:    'auth-proxy.customer.com',
    cdnHost:     'cdn-proxy.customer.com',
    apiHost:     'api-proxy.customer.com',
    forceLongPolling: false, // optional, default false
  },
}}>
  <App />
</VeltProvider>

proxyConfig fields

Field	Purpose	Covered by this repo?
v2DbHost	Proxy host for the v2Db service	✅
v1DbHost	Proxy host for the v1Db service. Replaces the dynamic database host in all v1Db URLs.	✅
storageHost	Proxy host for the Storage service	✅
authHost	Proxy host for the Auth service	✅
cdnHost	Proxy host for SDK bundle delivery (/lib/* passthrough to cdn.velt.dev)	✅
apiHost	Proxy host for the Velt API (Velt's own backend)	✅
forceLongPolling	Force long-polling for v2Db and v1Db instead of WebSocket	optional, default false

All fields are optional. Omit any field you don't want to proxy and the SDK will talk to the default host directly for that one.

Coming soon

AWS (API Gateway + Lambda@Edge), Google Cloud Run, Vercel Edge, and Kubernetes ingress recipes are on the roadmap. Contact Velt support if you need one of these sooner.

Support

Questions, issues, or platform requests: contact your Velt support channel.