Configuration

Vesper reads two files, and neither is required. vesper() with no options and no vesper.config.ts is a complete setup: every collection gets a form built from its schema.

vesper() in astro.config.mjs

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vesper from '@vesper/astro';

export default defineConfig({
  site: 'https://www.example.edu',
  integrations: [
    vesper({
      siteName: 'Riverside College',
      search: { filters: { news: ['tags'] } },
      a11y: { failBuildOn: 'error' },
    }),
  ],
});

a11y

search

vesper({
  search: {
    filters: { blog: ['tags', 'author'] },
    sort: { blog: ['publishedAt'] },
    exclude: ['/tags/**'],
    strings: { fr: { button: 'Rechercher' } },
  },
});

github

GitHub mode is on in built sites only; astro dev always saves to your files.

vesper({ github: { relay: 'https://vesper-github-relay.your-account.workers.dev' } });

cloud

The cloud is on in built sites only. A site can have GitHub mode too, and the sign-in screen then offers both.

vesper({ cloud: { project: 'site_…' } });

cloud: true reads the project ID from VESPER_PROJECT.

vesper.config.ts

vesper.config.ts sits next to astro.config.mjs (.mts, .js and .mjs work too). It holds how the studio presents your content and where entries live on the site, never field definitions. Every key is optional. A key Vesper doesn't know is ignored with a warning, so a config written for a newer version still loads, and a value of the wrong type is reported with what it should be. A change to the file restarts the dev server.

// vesper.config.ts
import { defineConfig } from '@vesper/astro/config';

export default defineConfig({
  timeZone: 'America/New_York',
  collections: {
    pages: { url: '/:path', tree: true, maxDepth: 3, icon: 'panels-top-left' },
    news: { label: 'News', url: '/news/:slug', listFields: ['publishedAt'], icon: 'newspaper' },
    settings: { label: 'Site settings', singleton: true },
  },
  images: { ratios: { wide: 16 / 9, square: 1 } },
});

Roles and what each person may edit are set in the cloud's dashboard, not here. A roles key is ignored with a warning.

collections

Keyed by the collection's name in src/content.config.ts. A name that isn't a collection gets a warning.

A url pattern is built from tokens:

• :id is the entry's ID.
• :path is the ID without a trailing /index. A top-level index is the collection's root.
• :slug is the last part of the path.
• :title, or any other field's name, is that field's value.
• :publishedAt|yyyy, |mm and |dd are parts of a date field. A date with a time is read in the site's timeZone.

Addresses follow Astro's base, trailingSlash and build.format. The studio, links, redirects, breadcrumbs, search and the build's accessibility report all use the same url. For anything a pattern can't say, give a function. It gets the entry's id, collection and data (the frontmatter, typed unknown, so check a field before using it) and returns its path on the site. Keep it pure, with no server-only imports, because the studio runs it in the browser too:

collections: {
  news: { url: '/news/:publishedAt|yyyy/:slug' },
  people: { url: (entry) => `/people/${entry.id}` },
},

/admin and /_vesper are Vesper's, so no page may live there. See Pages and URLs for trees, section pages and moves.

images

See Images.

a11y

a11y: {
  blockPublishOn: ['missing-alt'],
  backgrounds: { 'Page, light': '#ffffff', 'Page, dark': '#12151f' },
},

The rule names are on Accessibility checks.

redirects

Every host also gets an HTML redirect page at each old address. See Hosting.

timeZone

An IANA time zone name, such as 'America/New_York'. The studio shows and takes times in it, and stores them as ISO 8601 with the offset. Date tokens in url and dates in search results use it too. Without it, each editor sees their own time zone, and addresses use UTC.

markdoc

Your tags stay in markdoc.config.mjs, and the studio builds each tag's settings from their attributes. These hints only add words for editors:

markdoc: {
  tags: {
    callout: {
      label: 'Callout',
      summary: 'type',
      attributes: {
        type: { labels: { note: 'Note', tip: 'Tip', warning: 'Warning' } },
        title: { description: 'Shown above the callout.' },
      },
    },
  },
},

mdx

MDX components declare their props nowhere the studio can read, so they're edited as blocks only when you declare them here, with a Zod schema from astro/zod. Other components stay as protected source.

import { z } from 'astro/zod';
import { defineConfig } from '@vesper/astro/config';

export default defineConfig({
  mdx: {
    components: {
      YouTube: { label: 'YouTube video', props: z.object({ id: z.string(), title: z.string() }) },
      Aside: { label: 'Aside', children: true, props: z.object({ title: z.string().optional() }) },
    },
  },
});

See Markdoc and MDX.

widgets

Your own React controls for fields:

widgets: {
  'store-hours': {
    component: () => import('./src/cms/StoreHours.tsx'),
    accepts: (field) => field.kind === 'array',
    match: (field) => field.path.at(-1) === 'hours',
  },
},

Vesper compiles widget files with React's automatic runtime, so your site doesn't need @astrojs/react. Start each widget file with /** @jsxImportSource react */ so TypeScript checks it as React. A widget that fails to load falls back to the built-in control, with a note.

See Fields.