Previews

Push a branch that is not your default branch and Camplax deploys it to its own URL:

https://<branch>--<slug>.camplax.app

feature/login-redesign on the project my-app becomes https://feature-login-redesign--my-app.camplax.app. The branch part is cleaned up to be a legal hostname — lowercased, punctuation turned to dashes — and a very long branch name is shortened with a small hash so two similar names cannot collide. The URL is in the deploy's output (camplax deploy --json prints it), on the Deploys page, and on the pull request.

What a preview is

A preview is not a copy of the production site pointing at production data. It is a second, complete deployment of your app:

• Its own compute. The preview runs on its own instance, separate from the production app. It suspends when idle and wakes on the first request, so an unused preview does not burn anything.
• Its own secrets. A preview reads the production vault, then the preview layer, then any values you set for that specific branch — so STRIPE_KEY can be a test key on previews while production keeps the live one. The merge order is in Secrets.
• Its own database. A preview runs against a database branch created for that git branch — never the production tables. More on this below.
• Its own files. Uploads on a preview go to a separate storage prefix, so a test upload cannot appear in the live app.

Because none of it is shared, a broken migration or a half-finished feature on a branch cannot touch the real thing.

The database underneath

A preview deploy needs a database branch for its git branch, and it fails rather than fall back to production if none exists. Branches arrive two ways:

• Automatically — when a pull request opens (or is reopened or updated) on a connected repo, Camplax provisions the branch database before the preview deploy runs.
• By hand — on the Database page's branches tab, or POST /v1/projects/:slug/database/branches. Do this before camplax deploy --branch <name> on a project with no connected repo.

A branch database starts empty by default. Schema and seed data get there through your checked-in migrations and the seed tools on the Database page. When the pull request closes — merged or not — the preview's compute, DNS and database branch are torn down together, so the whole thing is disposable.

Or start it with production's data. If you want to test against something real, ask for a copy when the preview's environment is first created:

• camplax deploy --branch <name> --with-data, or POST /v1/projects/:slug/deploys with { "environment": "preview", "branch": "<name>", "withData": true }.
• For a preview that already exists, Recreate with production data on the Database page's branches tab (or POST /v1/projects/:slug/database/environments/<env-id>/recreate with { "withData": true }) tears it down and re-provisions it as a copy.

The copy is made from production's continuous backup, so it carries whatever was there moments ago — raw, including rows, tokens and personal data; nothing is sanitized. Ask for it only on previews that should have it, and remember anyone with the preview link can reach it. To inspect the copy directly, pick the environment in the selector at the top of the Database page.

Locking previews behind a password

Previews are reachable by anyone who has the link. If you would rather they were not, open Settings and switch on Password-protect previews. Enabling generates a password, shown once — copy it and hand it to whoever reviews previews.

How it works:

• Every preview URL for the project shows a lock page before any of your code runs. A correct password sets an HttpOnly cx_preview cookie that lasts seven days, per preview host.
• Rotating the password invalidates everyone's cookies — the cookie's signature is keyed by the password hash.
• Production is never locked, and health-check paths stay open so the platform can still tell the app is alive.
• The lock takes effect on the next preview deploy — it is part of the app's environment, not a switch on live traffic.

The gate is also on the API: GET/PUT /v1/projects/:slug/domains/preview-gate, where PUT accepts enabled, rotate and reveal.

Analytics and previews

Preview traffic is excluded from your analytics by default — a setting under Analytics → settings (excludePreview, on out of the box) — so a day of clicking through a branch does not bend your production graphs. Preview events that do arrive are kept separately and capped at 10,000 per month, against production's 250,000.

Shipping a preview to production

Merging the PR is the normal path — the merge lands on the default branch and deploys production. To ship the branch as production without merging, promote it:

POST /v1/projects/:slug/deploys/previews/<branch>/promote

Good to know

• Preview URLs only exist on *.camplax.app. Custom domains always reach production — you cannot point a custom domain at a branch.
• The newest push wins: pushing again to the same branch cancels the preview still building and queues a fresh one.
• A preview is tied to the branch name, so a renamed branch is a new preview, not a moved one.

Under the hood: each preview is its own cell environment — a Kubernetes namespace, its own Postgres database, its own R2 prefix and its own secrets scope — suspended when idle, deleted with the branch. A data copy is the database's WAL archive replayed into the preview's cluster, so the data never crosses a network boundary twice.