Into a voidbase project

You have an instance running with collections you made in the admin panel, and you want those collections in a repository. This is the destination to pick if you want it on your own Cloudflare account, because the npm layout is the one that can deploy there.

voidbase local ls                    # the name and port of each one
voidbase local start blog            # if it is not already running

Make the directory

A project is a directory with three tracked subdirectories and a package.json. init writes them into an empty directory.

mkdir blog-api && cd blog-api
bunx @voidbase-cloud/voidbase init          # or: npx @voidbase-cloud/voidbase init
bun install

What each one holds is on the project page, and one page per directory is in the reference.

Take the collections out of the instance

Export writes the schema, the rows and the uploaded files to a directory. Point it at whichever instance you have running and give it a superuser.

voidbase export ./snapshot --url https://blog-api.example.workers.dev --admin you@example.com:your-password

Only the first of those is part of the repository. The rows and the files are data, and data belongs in the instance, not in git. What git tracks is the whole rule.

Put them back as something tracked

Start the project's instance, then import the collections into it. Import applies a collections file to a running instance, so it needs the address and a superuser; the API is on 8090 and the panel is at /_/, both reading the directory you are looking at.

voidbase serve --dev

voidbase import ./snapshot/collections.json --url http://127.0.0.1:8090 --admin you@example.com:your-password

That gets the schema into this instance's database, and no further. The repository defines a schema through pb_migrations, so write the export down as one: a migration can apply a collections list directly, and a fresh clone or a deploy then builds the same collections without the import.

// pb_migrations/1757500000_collections.js
migrate((app) => {
  app.importCollections([
    // the contents of snapshot/collections.json
  ], false);
});

From here the panel is no longer where the schema changes. Edit the migrations and the next start applies them, which is what makes the change reviewable. --dev restarts when a hook or a migration changes.

Check it, then connect the repository

When the collections match what you exported, commit and connect it.

git init && git add . && git commit -m "the backend"
voidbase sync --repo you/blog-api

That deploys once and wires the repository to Cloudflare Workers Builds, so every later push is the deploy. How a push becomes a deploy covers the tokens it needs, and the project pipeline covers preview instances and what the build is allowed to read.

The old instance

Nothing here touched it. It is still running and still holds the records, which is deliberate: you can point an application at the new one, compare them, and delete the old one when you are satisfied. To move the rows and files across as well, voidbase migrate <from-url> <to-url> takes a backup on one side and restores it on the other, in either direction.

Deleting depends on where it was. A directory you can remove, a CLI instance goes with voidbase local rm, and one on Cloudflare goes with voidbase destroy, which takes the Worker, the database, the bucket, the queue and the domains with it.