Proxy Server

You can route Velt SDK traffic via reverse proxies on your own domain. This keeps all Velt-related network calls branded to your infrastructure and satisfies strict network policies that prohibit direct connections to third-party services.

The Velt SDK communicates with several backend services. You can proxy any combination of them:

1. CDN — the SDK bundle itself (proxyConfig.cdnHost)
2. API — Velt API calls (proxyConfig.apiHost)
3. Persistence Database — Velt persistence database (proxyConfig.v2DbHost)
4. Ephemeral Database — Velt realtime database (proxyConfig.v1DbHost)
5. Storage — file/attachment storage (proxyConfig.storageHost)
6. Auth — authentication token endpoints (proxyConfig.authHost)

See ProxyConfig reference for the full type definition.

Proxying the Velt SDK

To serve the Velt SDK via your own proxy server (e.g., nginx) instead of Velt’s servers, provide your proxy’s base URL.

• Velt will automatically append /lib/sdk@[VERSION_NUMBER]/velt.js to your proxyConfig.cdnHost to determine the full URL for fetching the SDK.
  • If proxyConfig.cdnHost is https://cdn.yourdomain.com, the SDK will be loaded from https://cdn.yourdomain.com/lib/sdk@[VERSION_NUMBER]/velt.js.
• Your proxy server must be configured to to forward requests from [your_proxyDomain] to https://cdn.velt.dev without any modifications to headers or any other content.

React / Next.js

<VeltProvider 
  config={{
    proxyConfig: {
      cdnHost: 'https://cdn.yourdomain.com'
    }
  }}
></VeltProvider>  

Other Frameworks

 const client = await initVelt('YOUR_API_KEY', {
   proxyConfig: {
     cdnHost: 'https://cdn.yourdomain.com'
   }
 });

Proxying Velt API calls

To serve the Velt APIs via your own proxy server (e.g., nginx) instead of Velt’s servers, provide your proxy’s base URL using proxyConfig.apiHost.

• Your proxy server should be configured to forward requests from your proxy host to https://api.velt.dev without any modifications to headers or any other content.

React / Next.js

<VeltProvider
  config={{
    proxyConfig: {
      apiHost: 'https://api.yourdomain.com',
    },
  }}
></VeltProvider>

Other Frameworks

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    apiHost: 'https://api.yourdomain.com',
  },
});

Proxying Persistence Database

To route Persistence Database (Velt v2 database) traffic through your proxy, set proxyConfig.v2DbHost.

• Your proxy server should forward requests to the persistence endpoint used by your Velt project without modifying headers or content.

React / Next.js

<VeltProvider
  config={{
    proxyConfig: {
      v2DbHost: 'https://persistence-proxy.yourdomain.com',
    },
  }}
></VeltProvider>

Other Frameworks

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    v2DbHost: 'https://persistence-proxy.yourdomain.com',
  },
});

Proxying Ephemeral Database

To route Ephemeral Database (Velt v1 database) traffic through your proxy, set proxyConfig.v1DbHost. This replaces the firebaseio.com domain in all RTDB URLs.

• Your proxy server should forward requests to *.firebaseio.com without modifying headers or content.

When v1DbHost is set, the SDK host-locks RTDB by overriding the Firebase SDK’s internal host property setter. This prevents Firebase’s handshake from redirecting traffic to a shard server (s-gke-*.firebaseio.com), keeping all RTDB requests on your proxy domain for the lifetime of the connection.

React / Next.js

<VeltProvider
  config={{
    proxyConfig: {
      v1DbHost: 'https://rtdb-proxy.yourdomain.com',
    },
  }}
></VeltProvider>

Other Frameworks

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    v1DbHost: 'https://rtdb-proxy.yourdomain.com',
  },
});

Proxying Storage

To route File Storage (file attachments, recordings) traffic through your proxy, set proxyConfig.storageHost. This replaces firebasestorage.googleapis.com.

• Your proxy server should forward requests to firebasestorage.googleapis.com without modifying headers or content.

React / Next.js

<VeltProvider
  config={{
    proxyConfig: {
      storageHost: 'https://storage-proxy.yourdomain.com',
    },
  }}
></VeltProvider>

Other Frameworks

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    storageHost: 'https://storage-proxy.yourdomain.com',
  },
});

Proxying Auth

To route Auth traffic through your proxy, set proxyConfig.authHost. This replaces both identitytoolkit.googleapis.com and securetoken.googleapis.com.

• Your proxy server should forward requests to both identitytoolkit.googleapis.com and securetoken.googleapis.com based on the request path, without modifying headers or content.

The SDK caches the auth proxy host in localStorage during initConfig(). On subsequent page loads, the cached value is applied synchronously before Auth can fire an internal token refresh, ensuring the refresh request goes through your proxy rather than directly to Google.

React / Next.js

<VeltProvider
  config={{
    proxyConfig: {
      authHost: 'https://auth-proxy.yourdomain.com',
    },
  }}
></VeltProvider>

Other Frameworks

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    authHost: 'https://auth-proxy.yourdomain.com',
  },
});

Full proxy configuration

To route all Velt traffic through your proxies, configure every host together. You can also set forceLongPolling: true to force persistence and ephemeral Database connections to use long-polling instead of WebSockets (useful when your proxy does not support WebSocket upgrades).

React / Next.js

<VeltProvider apiKey="YOUR_API_KEY" config={{
  proxyConfig: {
    cdnHost: 'https://cdn-proxy.yourdomain.com',
    apiHost: 'https://api-proxy.yourdomain.com',
    v2DbHost: 'https://persistence-proxy.yourdomain.com',
    v1DbHost: 'https://rtdb-proxy.yourdomain.com',
    storageHost: 'https://storage-proxy.yourdomain.com',
    authHost: 'https://auth-proxy.yourdomain.com',
    forceLongPolling: false,
  },
}}>
  <App />
</VeltProvider>

Other Frameworks

const client = await initVelt('YOUR_API_KEY', {
  proxyConfig: {
    cdnHost: 'https://cdn-proxy.yourdomain.com',
    apiHost: 'https://api-proxy.yourdomain.com',
    v2DbHost: 'https://persistence-proxy.yourdomain.com',
    v1DbHost: 'https://rtdb-proxy.yourdomain.com',
    storageHost: 'https://storage-proxy.yourdomain.com',
    authHost: 'https://auth-proxy.yourdomain.com',
    forceLongPolling: false,
  },
});

Integrity Check

To ensure the integrity of the Velt SDK, especially when served via a proxy, Velt leverages Subresource Integrity (SRI). Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch (for example, from a CDN or your proxy server) are delivered without unexpected manipulation.

• Default: false

React / Next.js

<VeltProvider apiKey='YOUR_API_KEY' config={{
  integrity: true,
}}>
</VeltProvider>

Other Frameworks

let client = await initVelt("YOUR_API_KEY", {
    integrity: true,
});