Deploying a Frontend
PocketBase Cloud hosts single-page applications with HTTPS on an address the
platform assigns — ideal for the frontend of the app whose data lives in your
PocketBase instance. Build your SPA with React, Vue, Svelte, Vite, or another
client-side tool that produces an index.html entry point and static assets.
All plans include frontend hosting (5 frontends on Free and Starter, unlimited on Pro).
There are two ways to ship one: upload a ZIP in the portal, or run
pbc frontend deploy in the project directory. The CLI path runs your
build, packages the output, and uploads it in one command.
Build-time configuration
Your PocketBase URL is baked in at build time. When you build locally —
pbc frontend deploy or a ZIP upload — it comes from your shell:
VITE_POCKETBASE_URL=https://<instance-id>.<compute>.pocketbasecloud.com npm run build
Copy the exact URL from the instance’s page in the portal, or from
pbc pocketbase info --name my-db.
When the platform builds the frontend from source (a GitHub push or a
template), it uses the frontend’s build environment instead. Values are
stored unencrypted and visible to anyone with access to the frontend, and
variables your framework exposes to the browser (such as VITE_ or
NEXT_PUBLIC_) end up in the public bundle. Both the dependency install and
the build see them, so a private-registry token such as NPM_TOKEN works.
Variables are limited to 10 KB in total, values of 8 or more characters are
masked in build logs, and a few names the build platform sets itself, such as
HOME and PATH, are reserved. Changes apply on the next build.
Using the portal
Add variables wherever you deploy:
- Create Frontend — under Build Environment, before the first deploy
- The Deploy dialog — shown when the files you drop are source code; changed variables are saved when you click Deploy
- The frontend’s overview — the Build Environment card below Deployments, then Save. Use this one before a GitHub build.
Until the first successful deploy these sections are open; afterwards they are collapsed to Build Environment · N variables and open with a click.
Add them one at a time, select Paste .env and paste a whole file, or select
Import .env, or drop the file onto the variables. Names already in the
list are updated; lines that are not NAME=value are skipped and reported.
File pickers hide dotfiles such as .env on macOS and Linux: press
⌘ Shift . (macOS) or Ctrl
H (Linux) in the picker to show them.
Using the CLI
pbc env set VITE_POCKETBASE_URL=https://<instance-id>.<compute>.pocketbasecloud.com --target frontend --name my-site
pbc env import .env.production --target frontend --name my-site
pbc env ls --target frontend --name my-site
pbc env rm VITE_POCKETBASE_URL --target frontend --name my-site
Step 1: Build your site
npm run build
This produces a folder containing your SPA entry point and static assets —
typically dist/ for Vite projects or build/ for Create React App.
The CLI runs this step for you as part of deploy, so you only need it by hand
for the portal path or to check the output before shipping.
Step 2: Deploy
Using the portal
- Open your project and go to the Frontends tab
- Click New Frontend — the name is auto-generated, edit it if you like
- Drag your project files, folders, or a ready-made ZIP into the upload
area. Local junk (
node_modules,.git,.env*, logs) is stripped before upload, and wrapper folders are unwrapped for you, however deeply they nest. Drop a PocketBase or backend project here by mistake and the portal says so and links you to the right place - Review the file list and click Create — the first deploy ships with creation, so there is no separate upload step
Using the CLI
cd web
pbc frontend deploy --name web
That single command runs the build, zips the output directory, uploads it, creates the frontend if it doesn’t exist, and waits for it to come up.
pbc deploy --name web does exactly the same thing: it recognises a
static site — by its vite/svelte/vue/angular config, a bundler
dependency, or an index.html — and runs this command for you. See
One deploy command for all three.
| Flag | What it does |
|---|---|
--name <name> |
Which frontend to deploy. Asked for when omitted and nothing is linked. |
--skip-build |
Package the output directory without rebuilding |
--zip <file> |
Upload an archive you built yourself |
--location <loc> |
Region for the deployment (Starter) |
--compute <id> |
Compute to deploy onto. Asked for on Pro, and in an organization’s project, when there is more than one. List them with pbc compute ls. (Formerly --server, still accepted.) |
--env <name> |
Which pbc.json environment to target |
Step 3: Redeploy
Using the portal
Build and zip again, then open the frontend and click Deploy New Version — the dialog shows what was dropped as junk and previews the files going up. Every deploy is recorded in the Deployments list on the detail page.
Using the CLI
The first deploy records the frontend in web/pbc.json, so afterwards:
pbc frontend deploy # rebuild + redeploy the linked site
Rolling back
When a deploy breaks something, put the frontend back on an earlier successful deployment. Its build goes live again as a new deployment, so nothing is deleted and you can roll forward the same way. The last 20 successful builds of each frontend are kept for this. Build-time variables are part of the build, so they go back with it.
Using the portal
- Open the frontend — the Deployments list is on its detail page
- Click Roll back on the deployment to return to
- Check the build’s date and commit in the dialog and click Roll Back
For a frontend connected to GitHub, the dialog links the comparison of what the rollback undoes.
For a frontend that deploys from GitHub on every push, the rollback leaves the
repository alone unless you tick Also put the source in … back in the
dialog (--push-to-git with the CLI, pushToGit for an AI assistant). Then the
frontend’s root directory is put back as it was at the old build’s commit, so the
next push keeps the rollback. When the branch has commits that were not
deployed yet, or Review changes made in PocketBase Cloud is on in the
repository settings, a pull request is opened instead; merge it to keep the
rollback. Without it, the next push to the branch deploys over the rollback.
Each deployment in the list shows who deployed it (you, a teammate, or the commit’s author for a GitHub push), how, and the commit; its … menu opens the commit on GitHub.
Using the CLI
pbc frontend deployments # recent deployments, the live one marked
pbc frontend rollback # back to the success before the live one
pbc frontend rollback --to <id> # back to a specific deployment
rollback asks for confirmation; pass --yes in scripts. An AI assistant
connected through the MCP server does
the same with rollback_deployment.
How the CLI build is configured
The build command and output directory are inferred from your project (Vite,
SvelteKit, Angular, Next.js config, or the build script in package.json)
and written into pbc.json on the first deploy. Review the guess before
anything ships with:
pbc init frontend
// web/pbc.json
{
"projectId": "dhs4xnprgplurvo",
"kind": "frontends",
"defaultEnvironment": "production",
"environments": {
"production": { "id": "…", "name": "web" }
},
"build": {
"command": "npm run build",
"outputDir": "dist"
}
}
Edit that block whenever the guess is wrong — it is never overwritten. Add
exclude globs to drop files from the ZIP. .git, pb_data, .DS_Store,
.env, .env.*, *.log, and node_modules are always excluded.
Staging and production from one directory
pbc frontend deploy --name web-staging --env staging # creates + links
pbc environments # what this dir targets
pbc frontend deploy --env staging # from now on, no flags
Each environment is its own frontend in the same project — in the portal they
appear as two separate frontends, which is exactly what they are. A pbc.json
environment can override the build command:
{
"environments": {
"production": { "id": "…", "name": "web" },
"staging": {
"id": "…",
"name": "web-staging",
"build": { "command": "npm run build:staging" }
}
}
}
Your site is live
Provisioning takes under a minute. Your site is then live at an address the platform assigns from the frontend’s id and the compute it runs on:
https://<frontend-id>.<compute>.pocketbasecloud.com
You do not choose it and it never changes. To serve the site from an address people type, add a custom domain.
The exact URL is on the frontend’s page in the portal, and in the terminal:
pbc frontend ls
pbc frontend info --name web
Frontends are static files, so there are no container logs to stream — on either path, a failed page load is a build or routing problem, not a runtime one.
Custom domains
Using the portal
Add and verify a custom domain from the frontend’s detail page.
Using the CLI
pbc frontend domain add app.example.com --name web
pbc frontend domain verify app.example.com --name web
pbc frontend domain remove app.example.com --name web
Caching and redeploys
A redeploy is live for every visitor as soon as it finishes; nobody has to
clear their browser cache. HTML and files whose names stay the same between
builds (logo.png, config.json, anything in public/) are checked for a
newer version on every visit. Files whose names carry a build hash, such as
assets/index-BXk3a_9Q.js, are cached for a year, because every build that
changes them also renames them.
Tabs opened before a deploy keep working: the previous build’s hashed files stay available for two days, so a page that lazy-loads a chunk after the deploy still finds it.
Custom domains behind your own Cloudflare
If your custom domain is proxied through your Cloudflare account (the orange cloud), Cloudflare follows the same rules and you have nothing to do on deploy. The exception is a Cache Rule that caches everything or overrides the Edge Cache TTL or Browser Cache TTL: Cloudflare then ignores the platform’s caching rules and keeps serving the old files. Either remove that override for the domain, or purge the cache in your Cloudflare dashboard (Caching → Configuration → Purge Everything) after each deploy.
Single-page app routing
Client-side routers such as React Router and Vue Router handle navigation in
the browser. PocketBase Cloud falls back every application route to
index.html, so deep links like /dashboard/settings load your SPA and let
the client-side router render the correct screen.
Talking to PocketBase from the browser
Your frontend calls the PocketBase instance directly — see Connecting Your App. Both services are served over HTTPS on the same platform, so there are no mixed-content or certificate issues to deal with.
Remember that anything shipped to the browser is public: the instance URL is fine to expose, and per-user data protection belongs in your collection’s API rules, not in frontend code.
Full-stack in one project
A typical production setup on PocketBase Cloud is one project containing:
- a PocketBase instance — database, auth, files
- a frontend — your static UI
- optionally a backend — server-side code for payments, webhooks, or server-rendered pages (Pro plan)
From the CLI it’s one directory per resource, each linked once:
cd db && pbc pocketbase deploy --name my-app-db
cd ../api && pbc backend deploy --name my-app-api
cd ../web && pbc frontend deploy --name my-app-web