Skip to content

Install

You need Node 22.23.4 or newer.

The repository has a small site that is plain Astro: pages built from sections, a blog, a contact form and a menu. It is the fastest way to see the CMS, and the best thing to copy from. It needs pnpm 10.

Terminal window
git clone https://github.com/Velocity-Astro/velocity-cms.git
cd velocity-cms
pnpm install
pnpm build
cd examples/starter
npx velocity-cms init you@example.com "Your Name"
npm run seed
npm run dev

init prints a link that signs you in. Open it once the site is running, then open Pages and change something.

In an Astro site that has a server adapter:

  1. Set the site up.

    Terminal window
    npx velocity-cms init you@example.com "Your Name"

    This writes a secret and the local address to .env, keeps .env and the database’s folder out of git, adds velocityCms() to the Astro config and makes you the site’s owner. It can be run again: it adds only what is missing and never changes a value that is there.

  2. Describe your content. See Content types and fields.

  3. Draw it. See Showing content and The page builder.

Without an email and a name, init stops after the setup. Make the owner later with npx velocity-cms owner <email> <name>. npx velocity-cms link <email> prints a new sign-in link for someone who already has access.

astro.config.mjs
import { defineConfig, memoryCache } from 'astro/config';
import node from '@astrojs/node';
import velocityCms from '@velocity-astro/cms-astro';
export default defineConfig({
site: process.env.SITE_URL || 'http://localhost:4321',
adapter: node({ mode: 'standalone' }),
integrations: [velocityCms({ siteName: 'My site', entryPages: ['pages'] })],
// A page drawn from the CMS is kept until a publish clears it. A day is the backstop.
cache: { provider: memoryCache() },
routeRules: { '/[...path]': { maxAge: 86400, tags: ['cms'] } },
});
OptionWhat it is for
siteNameShown in the editor, in sign-in emails and in the passkey prompt.
entryPagesThe content types whose entries are pages one route draws, such as ['pages']. Their addresses join the sitemap and search.
pluginsThe site’s own plugins: package names or files. See Writing a plugin.
mailerA file that delivers sign-in links by email. See People and sign-in.
imagesA folder of images that image fields can choose from, such as './src/assets/photos'.
unlistedAddresses to leave out of the sitemap, such as ['/search/'].

The CMS reads its settings from the environment, and from .env while you develop and build.

Variable
VELOCITY_CMS_SECRETRequired. At least 32 characters. Signs sessions and preview links and seals plugin secrets. init makes one.
VELOCITY_CMS_ORIGINThe site’s address, such as https://example.com. Not needed when site is set in the Astro config.
VELOCITY_CMS_DATABASE_URLWhere the database is. Left out, a file at cms/data.db.
VELOCITY_CMS_DATABASE_TOKENThe token of a hosted libSQL database.
VELOCITY_CMS_RESEND_API_KEY, VELOCITY_CMS_EMAIL_FROMSend sign-in links and invitations through Resend.
VELOCITY_CMS_MEDIA_DIRA folder for uploaded images.
VELOCITY_CMS_S3_BUCKET, VELOCITY_CMS_S3_ENDPOINT, VELOCITY_CMS_S3_ACCESS_KEY_ID, VELOCITY_CMS_S3_SECRET_ACCESS_KEYA bucket for uploaded images. All four, or none. VELOCITY_CMS_S3_REGION is optional.

Any machine that runs Node and keeps its disk.

  1. Set VELOCITY_CMS_SECRET and the site’s address on the machine.
  2. Build and start the site as you would any Astro site on the Node adapter.
  3. Make the owner once, on the machine: npx velocity-cms owner you@example.com "Your Name".

The database is the file cms/data.db and uploads go in cms/media, beside it. Back that folder up.

A serverless host has no disk to keep, so the database and the uploads live elsewhere.

  1. Create a libSQL database, for example on Turso, and set VELOCITY_CMS_DATABASE_URL and VELOCITY_CMS_DATABASE_TOKEN in the project’s settings.
  2. Set VELOCITY_CMS_SECRET, and site in the Astro config (or VELOCITY_CMS_ORIGIN).
  3. Use the Vercel adapter in place of the Node one, and deploy.
  4. Make the owner from your own machine, with the same four variables in your shell or .env: npx velocity-cms owner you@example.com "Your Name".

For uploads, set the four VELOCITY_CMS_S3_* variables to any S3-compatible bucket, such as Cloudflare R2. Without them a site on a hosted database takes no uploads, and the editor does not offer any.

Scheduled publishing needs no timer: the site looks for what is due whenever a page is asked for. On a quiet site that can be late. A scheduled job (cron, or your host’s own) that calls one address makes it exact:

Terminal window
curl -H "Authorization: Bearer $VELOCITY_CMS_SECRET" https://example.com/api/cms/schedule