Backend

Añade el backend de PocketBase a un proyecto que no lo tiene — un proyecto generado a partir de la plantilla estática, uno al que se le quitó el backend, o un proyecto SvelteKit que Vela no creó, como uno de npx sv create. Añade el backend y la infraestructura de tests de servidor y nada más; vela bless es la conversión completa.

Sintaxis

$ vela enable backend

Se te pedirá el correo electrónico y la contraseña del administrador para la nueva base de datos PocketBase, el mismo par que piden vela create y vela bless. Si esas credenciales ya están en tu entorno — por ejemplo en un .env que el proyecto conservó tras un vela disable backend anterior — se reutilizan en lugar de volver a preguntarlas.

Opciones

  • --email <email> - Correo electrónico del superusuario de PocketBase
  • --password <password> - Contraseña del superusuario de PocketBase, de al menos 8 caracteres

Fuera de una terminal, por ejemplo en CI, no hay dónde preguntar: pasa ambas opciones, o ten ya POCKETBASE_SUPERUSER_EMAIL y POCKETBASE_SUPERUSER_PASSWORD en el entorno.

Qué hace

Esto instala @velastack/pocketbase, pocketbase-sveltekit, @velastack/kit y @sveltejs/adapter-node, además de vitest, supertest y @types/supertest para los tests de servidor, y después:

  • Añade el handle de PocketBase a src/hooks.server.ts, y crea el archivo si no existe
  • Genera el directorio data/ desde el que se ejecuta la base de datos, con fixtures/, hooks/ y seeds/ dentro
  • Cambia el adaptador de SvelteKit de @sveltejs/adapter-static o @sveltejs/adapter-auto a @sveltejs/adapter-node
  • Añade a .gitignore un bloque de PocketBase que ignora la base de datos de data/ pero conserva fixtures/, hooks/ y seeds/
  • Escribe test/setup.ts, que da a cada test de servidor clientes de PocketBase y un usuario de prueba nuevo. Un test/setup.ts existente se reemplaza.
  • Escribe vitest.config.ts, el proyecto de tests de servidor que ejecuta vela test:server, cuando el proyecto no configura vitest en ningún sitio: ni vitest.config.* ni vitest.workspace.*, ni un bloque test en vite.config. Sin él, test/setup.ts nunca se carga.

Un hooks.server.ts existente conserva sus handles. handlePocketbase ocupa el lugar del handleStatic() de la plantilla estática; si no lo hay, se añade al final de una sequence, así que los handles que ya estaban se ejecutan primero. Si un archivo tiene una forma que Vela no sabe editar — otro adaptador, o un handle que no puede componer — se deja tal cual y se te muestran las líneas que hay que cambiar a mano.

El superusuario

Una vez colocados los archivos, la base de datos recibe su superusuario y se escriben POCKETBASE_SUPERUSER_EMAIL y POCKETBASE_SUPERUSER_PASSWORD en .env — de donde los lee cada comando vela, y que la plantilla ya ignora en git. Sin ese par, vela dev inicia una base de datos contra la que nada puede autenticarse y cualquier otro comando se detiene en la comprobación de credenciales, así que esto es lo que hace que el backend sea utilizable y no solo esté instalado.

POCKETBASE_URL no es una de ellas: vela dev, vela build y vela preview inician PocketBase en un puerto libre y la definen ellos mismos para la aplicación. Defínela tú solo para apuntar un comando a una base de datos que ya esté en marcha.

Volver a ejecutar el comando es seguro. Se reutilizan las credenciales de .env y el superusuario se inserta o actualiza, así que el archivo y la base de datos no pueden acabar en desacuerdo.

Una vez habilitado, vela dev inicia la base de datos junto a la aplicación y la interfaz de administración está disponible en /admin. Todo lo demás que necesita una base de datos — auth, la API, los scaffolds, los seeds y los fixtures — depende de esto.

Sin shadcn-svelte

vela enable auth escribe páginas de shadcn-svelte, y rechaza un proyecto que no tiene components.json ni el paquete shadcn-svelte; consulta vela bless. En un proyecto así, los siguientes pasos que imprime el comando apuntan a lo que sí funciona allí: vela generate scaffold, que escribe sus páginas en HTML plano, y vela test:server para el test de servidor que lo acompaña.

Cómo se detecta un backend

Un proyecto tiene backend cuando tiene un directorio data/ y depende de pocketbase-sveltekit o de @velastack/pocketbase. El directorio solo no basta: también es donde un CMS autoalojado guarda su base de datos, en un proyecto que puede no tener PocketBase. Un comando que necesita la base de datos se detiene en un proyecto que no la tiene:

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.

Revertir

vela disable backend lo vuelve a quitar.