Set up a preview environment for every pull request

A preview environment is a full copy of your app, deployed from a pull request, at its own URL. Reviewers click a link instead of pulling the branch, and product and design can check a change before it merges. This guide sets one up in about ten minutes.

Install the CLI

You need the CLI to link the repository and to test the setup locally.

npm install -g @cloud/cli

pnpm add -g @cloud/cli

yarn global add @cloud/cli

bun add -g @cloud/cli

Then log in and link the project in the root of your repository:

cloud login
cloud link --project web-frontend

Turn on previews

The project file sits in the root of the repository, next to package.json:

Previews are configured in the project file. The previews block says which branches get one, which environment variables they use, and how long they live after the pull request closes.

import { defineConfig } from "@cloud/cli";

export default defineConfig({
  service: "web-frontend",
  previews: {
    branches: ["*", "!main"],
    env: "preview",
    expireAfter: "3d",
  },
});

Commit the file and open a pull request. The first preview builds in the same time as a normal deploy, and the bot comments the URL on the pull request.

Give each preview its own data

A preview that writes to the staging database is not really isolated. Add a database branch so every preview starts from a copy of the schema and a small seed:

previews: {
  branches: ["*", "!main"],
  env: "preview",
  database: { branchFrom: "staging", seed: "./db/seed.sql" },
},

Database branches are copy-on-write, so creating one takes a few seconds, whatever the size of the parent.

Clean up

When the pull request merges or closes, the preview and its database branch are deleted after expireAfter. To delete one sooner, run:

cloud previews delete --pr 142

That is all. From now on, every pull request gets a link, and nothing is left running after it closes.