Bless

Upgrade an existing, vanilla SvelteKit project into a VelaStack project — the equivalent of vela create for a repository that already exists.

There are two routes into an existing project. vela bless is the all-in-one upgrade: Tailwind, shadcn-svelte and its components.json, Vela’s layout and routes, and the PocketBase backend. vela enable backend adds only PocketBase and the server test harness, and leaves everything else alone. Much of Vela needs neither; see Without blessing below.

Syntax

$ vela bless [path]
$ vela bless                 # the project in the current directory
$ vela bless ./my-app

You’ll be prompted for the admin email and password for the new PocketBase database. Blessing a project that has already been blessed is refused.

Options

  • --template <type> - Template to scaffold from, defaults to minimal. Only templates with a backend can be used — blessing is what adds PocketBase to a project.
  • --email <email> - Email of the admin user
  • --password <password> - Password of the admin user, at least 8 characters
  • --install <package-manager> - Install dependencies with the given package manager, or --no-install to skip
  • --skip-routes - Preserve src/routes even if it looks untouched
  • --force-routes - Replace src/routes with the Vela template without detection

--skip-routes and --force-routes are mutually exclusive.

What it adds

Files Vela owns outright are written in. If your project already has one, it is kept and you’re told what Vela’s copy would have carried:

src/hooks.server.ts          the handlePocketbase hook
src/lib/server/workflows.ts  the workflow client and the worker hooks.server.ts starts
src/app.css                  Tailwind imports and theme tokens
src/lib/utils.ts             the cn helper and component type utilities
src/lib/index.ts             a $lib placeholder
src/lib/site.ts              the app's name, taken from package.json, and its URL
components.json              the shadcn-svelte config `vela ui add` reads
.npmrc                       engine-strict=true
.ignore                      search ignores for generated files
vitest.config.ts             the server test project `vela test:server` runs

Directories are added alongside what you have: src/lib/components, src/lib/workflows, data, test and static. Configuration is merged rather than overwritten:

svelte.config.js
vite.config.ts
tsconfig.json
package.json
.gitignore
src/app.d.ts

Your project’s SvelteKit adapter is kept: if package.json already lists one, the template’s @sveltejs/adapter-node isn’t added. .gitignore gains only the entries it’s missing, among them /data/* for the local database (with data/fixtures, data/seeds and data/hooks still tracked) and /backups.

Routes

Vela looks at src/routes to decide whether it is still the untouched npx sv create placeholder. If it is, it is replaced with the template’s routes; if you have written anything real, it is left alone. Override the detection either way with --skip-routes or --force-routes.

Without blessing

These work in a project straight from npx sv create, with no setup:

Generated routes go straight under src/routes in a project without Vela’s (public) and (app) groups.

These write shadcn-svelte markup or drive shadcn-svelte itself, so they need a components.json and the shadcn-svelte package:

In a project without them they refuse before changing anything, and print the two commands that set it up:

$ npx sv add tailwindcss
$ npx shadcn-svelte@latest init

The commands that need a database say so the same way, and point at vela enable backend. Once it has run, vela generate scaffold works without shadcn-svelte too, with its pages in plain HTML.