Networking
How networking works in BrowserPod, and the differences between Edge and fetch networks.
A Pod connects to the internet using one of two network types. Both carry outgoing HTTP, HTTPS, and WebSocket traffic. On both, programs in a Pod reach each other’s servers on localhost.
- Edge network: Routes traffic through BrowserPod Edge. It requires an API key and is charged per connected hour, in blocks of 10 tokens (see Licensing for the free allowance).
- It can reach its allowed domains: BrowserPod’s default domains, such as the npm registry and GitHub, or the ones you choose with Edge Pro in the BrowserPod console
.
- Besides HTTP, HTTPS, and WebSocket, it carries other TCP connections to its allowed domains.
- It enables Portals, which let you preview and share services running inside your Pod.
- It can reach its allowed domains: BrowserPod’s default domains, such as the npm registry and GitHub, or the ones you choose with Edge Pro in the BrowserPod console
- Fetch network: Routes traffic directly through the browser’s standard
fetch(). It’s free and needs no API key.
- It carries HTTP, HTTPS, and WebSocket traffic only, with no other TCP connections.
- It can reach servers that allow cross-origin requests (CORS). npm needs one extra setup step.
- It doesn’t support Portals.
Choosing a network
BrowserPod.boot picks the network based on whether you pass an apiKey.
Pass an API key to boot on the Edge network:
const pod = await BrowserPod.boot({ apiKey: "your_key_here" });Omit it to boot on the fetch network:
const pod = await BrowserPod.boot();To customize network settings, create a network object with createEdgeNetwork or createFetchNetwork and pass it to boot as network, as in Using npm without an API key below. Each network object can be used by one Pod only. When you pass network, don’t also pass apiKey to boot; give it to createEdgeNetwork instead.
Using npm without an API key
On a plain fetch network, npm install fails: npm adds headers to its requests that the registry doesn’t accept, so the browser blocks them. To use npm without an API key, create the fetch network with opinionatedFetch:
const network = await BrowserPod.createFetchNetwork({ fetch: BrowserPod.opinionatedFetch,});const pod = await BrowserPod.boot({ network });Fetch network and CORS
Requests on a fetch network come straight from the browser, so they follow the browser’s Cross-Origin Resource Sharing (CORS) rules: a server must allow requests from your page’s origin, or the browser blocks them.
To reach a server that doesn’t allow this, boot on the Edge network with an API key, or route requests through your own proxy with a custom fetch handler.
Fetch network and WebSockets
WebSocket connections work on a fetch network with no extra setup. Only a custom fetch function that handles WebSocket traffic itself, instead of forwarding it, has to complete the upgrade; see createFetchNetwork.