Skip to content

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

  1. Open your project and go to the Frontends tab
  2. Click New Frontend — the name is auto-generated, edit it if you like
  3. 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
  4. 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

  1. Open the frontend — the Deployments list is on its detail page
  2. Click Roll back on the deployment to return to
  3. 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

Next steps