Preview URLs

When you work with CodeSandbox, every port opened by your dev server is available behind a URL that looks like this:

https://{id}-{port}.csb.app

For example, while writing this blog post I'm previewing my changes at https://rfjmrz-3000.csb.app.

This is different compared to working on your local machine, where the dev server is often available behind http://localhost:{port}. We'll guide you through how you can integrate more easily with the new URL structure.

Automatic Proxy

We're injecting code automatically in the preview to proxy localhost:3000 and similar requests coming from the preview (e.g. your frontend code) to the right hostname. You can learn more about that here (opens in a new tab).

Generating preview URLs

Unlike localhost URLs, csb.app URLs differ per branch. The advantage of this approach is that you can share a preview URL with a co-worker and start working on a new branch while they check out your work. However, it does require some additional configuration to support this.

JavaScript library

We've created a (zero-dependency) JavaScript library (opens in a new tab) that simplifies getting the current hostname. You can install the library by running one of the following three commands:

npm i @codesandbox/utils
pnpm i @codesandbox/utils
yarn add @codesandbox/utils

After installing the library, you can get the preview URL for the current VM like so:

import { getCodeSandboxHost } from '@codesandbox/utils';
 
const port = 3000;
const previewUrl = `https://${getCodeSandboxHost(port)}`;

This library works both in the frontend and in the backend. In the frontend it will base the preview id on the current URL, in the backend it will use hostname to determine the current preview id.

Here's a running example:

Using hostname

You can programmatically get the current branch or devbox ID by checking the hostname of the machine. This is guaranteed to work between live clones of VMs as well.

You can use this to generate a preview URL, here's an example in JavaScript:

const hostname = require('os').hostname;
const port = 3000;
 
const previewUrl = `https://${hostname}-${port}.csb.app`;

Or alternatively you can run hostname as a shell command to get the latest hostname.

Using RegEx in the browser

If you want to get the current preview id in the frontend, and you don't want to use the JavaScript library mentioned earlier, you can use a RegEx based on the current URL to get the current preview id. Like so:

const REGEX = /(?<id>\w{5,6})-(?<port>\d{1,5})\.(?<hostname>.*)/;
 
function getPreviewUrl(port) {
  const currentUrl = location.host;
  const currentMatch = currentUrl.match(REGEX);
 
  if (!currentMatch?.groups) {
    return undefined;
  }
  const { id, hostname } = currentMatch.groups;
 
  if (!id || !port || !hostname) {
    return undefined;
  }
 
  return `${id}-${port}.${hostname}`;
}

The same code can be found here (opens in a new tab).

Using environment variables

CodeSandbox exposes two environment variables inside the VM that you can use to determine the hostname:

• CSB_BASE_PREVIEW_HOST, this is csb.app by default
• CODESANDBOX_HOST, this is :id-$PORT.csb.app by default, for example: rfjmrz-$PORT.csb.app.

Generally we recommend to use hostname instead of environment variables, as using environment variables requires restarting the task on every fork.

Forwarding Ports

You can also opt to forward the ports to localhost. The disadvantage is that anyone would have to forward the port to localhost to see the preview, but it requires zero configuration.

You can do this by opening the project inside VSCode, and clicking on "Ports" in the bottom panel. From there you can forward any HTTP or TCP port to your machine.

Common Troubleshooting

"Invalid Host/Origin header"

The Webpack dev server is by default configured to only allow requests originating from localhost. Because of this, Webpack will reject requests from the preview with an "Invalid Host/Origin header" error.

You can fix this by updating the Webpack configuration.

Webpack 4

For Webpack 4, you'd need to add this to your devServer entry in your webpack configuration:

disableHostCheck: true

Webpack 5

For Webpack 5, you'd need to add this to your devSever entry in your webpack configuration:

allowedHosts: ".csb.app",

CORS Headers

If a frontend server runs on a different port or branch than the backend server, and CORS is enabled, the backend will have to return CORS headers based on the caller URL.

There are two ways to approach this. If the server runs in the same branch/instance as the frontend, you can use the current preview id, like so:

const express = require('express')
const cors = require('cors')
const { getCodeSandboxHost } = require('@codesandbox/utils')
const app = express()
 
const FRONTEND_PORT = 3000
app.use(cors({
    origin: getCodeSandboxHost(FRONTEND_PORT)
}))

If the frontend and backend run in different branches or instances, you will need to use dynamic checking on csb.app. In Express this can be done like so:

const express = require('express')
const cors = require('cors')
const app = express()
 
const FRONTEND_PORT = 3000
app.use(cors({
    origin: /\.csb\.app$/
}))

OAuth Login

Adding support for OAuth sign in depends on the provider that you're looking to support. Some OAuth providers support wildcard subdomains, which will make it work with CodeSandbox.

If the provider does not support wildcard subdomains, we recommend using another sign in method, like username/password based sign in or token-based login.