Create a project

A backend you extend and keep: your own endpoints, handlers that run when records change, a schema in version control. It runs as one process on your machine and as one Worker on Cloudflare, from the same directory.

Start one

bun i -g @voidbase-cloud/voidbase

mkdir blog-api && cd blog-api
voidbase init
voidbase superuser upsert you@example.com your-password
voidbase serve

That is a working instance on http://127.0.0.1:8090, with the admin panel at /_/, the API reference at /api/docs and a sample endpoint answering GET /api/hello. init says what it wrote:

pb_hooks/, pb_migrations/ and pb_secrets/ ready (wrote pb_hooks/main.pb.js, .gitignore, .env, package.json, pb_secrets/main.ts)
.gitignore covers pb_data/, pb_secrets/secrets.json and .cloud/

next: voidbase serve   (the API on 8090, the admin panel at /_/), or bun install && bun run dev

Only pb_hooks/ and pb_migrations/ matter on day one. Each directory has its own page:

Or start from somebody's working project rather than empty directories. The files of the repository are downloaded as a tarball and unpacked into the directory, which has to be empty or absent; nothing is cloned and no .git is left behind, and the next steps are read from what the template contains.

voidbase templates                                  # what the marketplace lists: name, title, summary, repository
voidbase init blog-api --template voidbase-demo     # one of those, by name
voidbase init blog-api --template owner/name        # or any public GitHub repository, at --ref if not the default branch

The loop

1. Design the schema in the panel. Collections, fields, and the API rules that decide who may read and write what. It is the fastest way to get the shape right, and it is immediately live.

2. Write it down as a file in pb_migrations, so the same schema reaches production and the next person who clones this.

3. Add behaviour in pb_hooks: an endpoint the API does not have, a handler that fires when a record is written, a nightly job.

4. Run it while you work. On Bun, or on Cloudflare's own runtime without a token or an account, which is the one to use before a first deploy.

   Copy

   voidbase serve --dev              # restarts when a hook or a migration changes
   voidbase serve --dev --tunnel     # and on the internet meanwhile, at https://<words>.trycloudflare.com
   voidbase serve --workers          # the same project on Cloudflare's runtime, locally, with D1, R2, queue and hub in Miniflare

5. Type the client from it. The instance describes its own API at /api/openapi.json, and types turns that into a file your app imports, so a renamed field is a compile error rather than an empty value. The SDK page shows the other end.

   Copy

   voidbase types --url http://127.0.0.1:8090 --email you@example.com --password your-password
   # writes src/voidbase.ts: an interface per collection, a Collections map, a TypedPocketBase type

Put it on Cloudflare

One API token, which voidbase token prints the link for, declared as a local() key in pb_secrets and valued in its secrets.json. Then, from the project:

voidbase deploy

It creates the Worker, its database, its file storage, its queue and its realtime object on the first run, stores the declared secrets on it, applies any pending migrations on the first request, and prints the address. Deploy again whenever anything changes; the data is untouched, and a secret the Worker already holds is left alone.

voidbase deploy --domain api.example.com          # the domains plugin attaches it and turns workers.dev off
voidbase deploy --database durable                 # the data in a SQLite-backed Durable Object instead of D1
voidbase deploy --preview feature/login            # a second Worker for the branch, seeded from production
voidbase deploy --dry-run                          # the whole plan, nothing touched

Or let a push do it

sync is that deploy plus the wiring, so every later push to the repository deploys by itself and every change to the instance is a commit somebody can read and revert.

voidbase sync

It needs a second token and one dashboard step the first run points at. From then on the whole loop above is: edit, commit, push. Deploy on every push is the guide, and What git tracks is the list of what belongs in the repository and what must not.

voidbase update

When this stops being enough

A project is a backend. When the site is yours too and you would rather write pages, typed routes and a database schema in one application than keep a frontend and a backend in step, the voidbase stack is the next page.

voidbase templates                                              # what the marketplace lists
voidbase init blog-api --template voidbase-site                 # by listed name
voidbase init blog-api --template voidbase-cloud/voidbase-demo  # any public repository, at its default branch
voidbase init blog-api --template acme/starter --ref v2         # at a branch or tag
voidbase init blog-api --template starter --marketplace https://templates.acme.internal   # another listing

voidbase init blog-api && cd blog-api

voidbase plugins add echo         # writes pb_plugins/echo and the lock entry
git add pb_plugins voidbase.lock  # the install is a commit, like any dependency
voidbase deploy                   # and the deploy is what puts it live (or push, if a pipeline deploys)