Backend

Add the PocketBase backend to a project that doesn’t have one — a project scaffolded from the static template, one where the backend was removed, or a SvelteKit project Vela did not create, such as one from npx sv create. It adds the backend and the server test harness and nothing else; vela bless is the full upgrade.

Syntax

$ vela enable backend

You’ll be prompted for the admin email and password for the new PocketBase database, the same pair vela create and vela bless ask for. Credentials already in your environment — from a .env the project kept through an earlier vela disable backend, say — are reused instead of being asked for again.

Options

  • --email <email> - Email of the PocketBase superuser
  • --password <password> - Password of the PocketBase superuser, at least 8 characters

Off a terminal, such as in CI, there is nothing to prompt on: pass both flags, or have POCKETBASE_SUPERUSER_EMAIL and POCKETBASE_SUPERUSER_PASSWORD in the environment already.

What it does

This installs @velastack/pocketbase, pocketbase-sveltekit, @velastack/kit and @sveltejs/adapter-node, plus vitest, supertest and @types/supertest for server tests, then:

  • Adds the PocketBase handle to src/hooks.server.ts, creating the file if there isn’t one
  • Scaffolds the data/ directory the database runs from, with fixtures/, hooks/ and seeds/ inside
  • Switches the SvelteKit adapter from @sveltejs/adapter-static or @sveltejs/adapter-auto to @sveltejs/adapter-node
  • Appends a PocketBase block to .gitignore that ignores the database in data/ but keeps fixtures/, hooks/ and seeds/
  • Writes test/setup.ts, which gives each server test PocketBase clients and a fresh test user. An existing test/setup.ts is replaced.
  • Writes vitest.config.ts, the server test project vela test:server runs, when the project configures vitest nowhere: no vitest.config.* or vitest.workspace.*, and no test block in vite.config. Without it test/setup.ts is never loaded.

An existing hooks.server.ts keeps its handles. handlePocketbase takes the place of the static template’s handleStatic(); otherwise it is added last in a sequence, so the handles already there run first. Where a file is in a shape Vela can’t edit — another adapter, or a handle it can’t compose — it is left alone and you’re shown the lines to change by hand.

The superuser

Once the files are in place the database gets its superuser, and POCKETBASE_SUPERUSER_EMAIL and POCKETBASE_SUPERUSER_PASSWORD are written to .env — where every vela command reads them from, and which the template already gitignores. Without that pair, vela dev starts a database nothing can authenticate against and every other command stops at the missing-credentials guard, so this is what makes the backend usable rather than merely installed.

POCKETBASE_URL is not one of them: vela dev, vela build and vela preview start PocketBase on a free port and set it for the app themselves. Set it yourself only to point a command at a database that is already running.

Re-running the command is safe. The credentials in .env are reused and the superuser is upserted, so the file and the database cannot end up disagreeing.

Once enabled, vela dev starts the database alongside the app and the admin interface is available at /admin. Everything else that needs a database — auth, the API, scaffolds, seeds and fixtures — depends on this.

Without shadcn-svelte

vela enable auth writes shadcn-svelte pages, and refuses a project that has no components.json and shadcn-svelte package; see vela bless. In such a project the next steps the command prints point at what works there instead: vela generate scaffold, which writes its pages in plain HTML, and vela test:server for the server test that comes with it.

How a backend is detected

A project has a backend when it has a data/ directory and depends on pocketbase-sveltekit or @velastack/pocketbase. The directory alone is not enough: it is also where a self-hosted CMS keeps its database, in a project that may have no PocketBase. A command that needs the database stops in a project without one:

vela migrate up needs a backend, and this project does not have one.

There is no PocketBase database here for it to talk to.

To add one, run vela enable backend.

Reverting

vela disable backend takes it back out.