# Backend

Add the PocketBase backend to a project that doesn't have one — a project scaffolded from the [static template](/static), 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`](/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`](/create) and [`vela bless`](/bless) ask for. Credentials already in your environment — from a `.env` the project kept through an earlier [`vela disable backend`](/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`](/test) 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`](/dev), [`vela build`](/build) and [`vela preview`](/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`](/dev) starts the database alongside the app and the admin interface is available at `/admin`. Everything else that needs a database — [auth](/enable/auth), [the API](/enable/api), [scaffolds](/generate/scaffold), [seeds](/seeds) and [fixtures](/fixtures) — depends on this.

### Without shadcn-svelte

[`vela enable auth`](/enable/auth) writes shadcn-svelte pages, and refuses a project that has no `components.json` and shadcn-svelte package; see [`vela bless`](/bless). In such a project the next steps the command prints point at what works there instead: [`vela generate scaffold`](/generate/scaffold), which writes its pages in plain HTML, and [`vela test:server`](/test) 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](/enable/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`](/disable/backend) takes it back out.