# Configuration

> Every option of vesper() in astro.config.mjs and every key of vesper.config.ts, with its default.

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

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vesper from 'vespercms';

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

| Option | Default | What it does |
|---|---|---|
| `siteName` | The host of Astro's `site`, else your package's name | The site's name in the studio's top bar and page titles, and on the search page. |
| `studio.deploy` | `true` | `false` leaves `/admin` out of production builds. It's still there in `astro dev`. |
| `imageService` | `true` | Wraps Astro's Sharp image service, when your site uses it, so the crops editors set are cut before Astro resizes each image. `false` leaves Astro's service alone; `<Img>` then uses Astro's own crop for each ratio, and manual crops aren't applied. |
| `a11y` | `{}` | The [accessibility check](/docs/site/accessibility/) at build. `false` turns it off. |
| `search` | `{}` | [Site search](/docs/site/search/). `false` turns it off: no index and no `/search` page. |
| `github` | Off | [GitHub mode](/docs/getting-started/publishing/): editors sign in with GitHub on the deployed site. |
| `cloud` | Off | [The cloud](/docs/getting-started/publishing/): editors sign in to Vesper, and saves are drafts until published. |

### a11y

| Key | Default | What it does |
|---|---|---|
| `failBuildOn` | `false` | `'error'` fails the build when the report has an error (axe's critical and serious issues). `'warning'` fails it on any issue. The report is written first. |

### search

| Key | Default | What it does |
|---|---|---|
| `filters` | None | Per collection, the fields offered as filters: text, lists of text, selects and references. |
| `sort` | None | Per collection, the fields results can be sorted by: dates, numbers and text. |
| `exclude` | `[]` | Pages to leave out, by path, with `*` and `**`, such as `'/tags/**'`. |
| `noJsLink` | The home page | Where `/search` sends visitors who have no JavaScript. |
| `noJsFallback` | None | `'duckduckgo'`: without JavaScript, the search form searches the site on DuckDuckGo. Needs Astro's `site`. |
| `strings` | English | The search interface's words in other languages, keyed by `<html lang>`. |

```js
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.

| Key | Default | What it does |
|---|---|---|
| `relay` | Required | The address of your sign-in relay: the `oauth-relay` template from Vesper's repository, deployed as a Cloudflare Worker. |
| `repo` | Read from the host's build environment, then git | The repository, as `owner/name`. |
| `branch` | The repository's default branch | Where publishes go. If git can't tell, `main`, and the build log says so. |
| `root` | Read from git | The site's folder inside the repository, for a monorepo. |
| `apiUrl` | `https://api.github.com` | For GitHub Enterprise Server: its API, such as `https://github.example.edu/api/v3`. |

```js
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.

| Key | Default | What it does |
|---|---|---|
| `project` | The `VESPER_PROJECT` variable | The site's project ID, from its settings in the dashboard. It's an identifier, not a secret. |
| `app`, `api` | `https://app.vespercms.com`, `https://api.vespercms.com` | For staging and tests only, and always set together, as here or with `VESPER_CLOUD_APP` and `VESPER_CLOUD_API`. |

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

`cloud: true` reads the project ID from `VESPER_PROJECT`.

A site built with its project ID also posts its [forms](/docs/site/forms/) to the cloud. Without one, each `<Form>` says it isn't connected yet, and the build warns.

## 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.

```ts
// vesper.config.ts
import { defineConfig } from 'vespercms/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 } },
});
```

| Key | What it holds |
|---|---|
| `collections` | How the studio presents each collection, and where its entries live. |
| `images` | The aspect ratios your site crops to, and the upload size limit. |
| `a11y` | The rules that block a save, and the colours your site draws text on. |
| `redirects` | Hosts to write native redirect rules for. |
| `timeZone` | The site's time zone. |
| `rebuildEvery` | How often, in minutes, the site is rebuilt on a schedule, so the studio can say when a scheduled entry goes live. |
| `markdoc` | Labels and help text for your Markdoc tags. |
| `mdx` | MDX components the body editor shows as blocks. |
| `widgets` | Your own editor controls. |

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.

| Key | Default | What it does |
|---|---|---|
| `label` | From the name: `blogPosts` is "Blog posts" | The collection's name in the studio, and its Section filter in search. |
| `icon` | A page; an outline for a tree; sliders for a singleton | A [Lucide](https://lucide.dev/icons) icon name, as that site lists it, such as `newspaper`. Install the `lucide` package to use one. |
| `url` | None | Where each entry lives on the site: a pattern or a function, below. |
| `tree` | `false` | Shows the collection as an outline: folders are sections, and an optional `_order.yaml` in each folder sets its order. Collections loaded with `glob()` only. |
| `maxDepth` | No limit | For a tree: how many levels deep a page may be, 1 or more. |
| `singleton` | `false` | The collection holds one entry, and the studio opens it directly. |
| `listFields` | None | Top-level fields shown as columns in the entry list, a select by its label. The first date field among them sorts the list, newest first, unless `listSort` says otherwise. |
| `listSort` | None | How the entry list is first sorted: `{ field, direction }`, where `field` is `'title'` or one of `listFields`, and `direction` is `'ascending'` (the default: A to Z, earliest first) or `'descending'`. Upcoming events read best as `{ field: 'startsAt', direction: 'ascending' }`. `orderBy` wins over it. |
| `orderBy` | None | For a collection that isn't a tree: a top-level number field that puts its entries in order, lowest first, then by title, with entries that have no number last. The list sorts that way, and editors drag an entry to a new place, which writes the number: usually only that entry's, halfway between its new neighbours'. Sort your pages by the same field so the site agrees. |
| `newEntryPath` | `:slug` | Where new entries are saved, inside the collection's folder, with `:slug`, `:year`, `:month` and `:day`. Trees place new pages under their parent instead. |
| `placement` | Each field's own `.meta({ placement })` | Per top-level field, the editor tab it's on: `'main'` for Content, `'details'` for Details, or a tab from `tabs`. |
| `tabs` | None | Editor tabs between Content and Details, by id with their labels, in order: `{ seo: 'SEO' }`. |
| `headingStart` | `2` | The level the body's top headings should have, from 1 to 6. Set `1` when the body holds the page's h1. |
| `search` | `true` | `false` leaves the collection's pages out of site search. |
| `schedule` | `false` | `true` lets editors schedule the collection's entries. An entry is on the site from its `publishAt` date until its `unpublishAt`, fields the collection's schema defines, and an optional `unpublishRedirect` page picker sends visitors elsewhere once it's gone. Each build decides once, so a time takes effect at the first build after it; set `rebuildEvery` so the studio can say when that is. An object renames the fields (`{ publishAt: 'goesLive' }`) or leaves out unpublishing (`{ unpublish: false }`). Without a schedule, a collection with a true-or-false `draft` field is unpublished by hand: a draft is left out of the build. |

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, or `undefined` when the entry has no page. Keep it pure, with no server-only imports, because the studio runs it in the browser too:

```ts
collections: {
  news: { url: '/news/:publishedAt|yyyy/:slug' },
  people: { url: (entry) => `/people/${entry.id}` },
  events: {
    url: (entry) => ((entry.data as { noPage?: boolean }).noPage ? undefined : `/events/${entry.id}`),
  },
},
```

`/admin` and `/_vesper` are Vesper's, so no page may live there. See [Pages and URLs](/docs/content/pages-and-urls/) for trees, section pages and moves.

### images

| Key | Default | What it does |
|---|---|---|
| `ratios` | Only `og` | Named aspect ratios, as width / height, such as `{ wide: 16 / 9, square: 1 }`. The studio previews each crop, and `<Img ratio="wide">` renders it. `og` (1.91:1, for social images) is always there. |
| `maxUploadEdge` | `3000` | Uploads whose longer edge is bigger, in pixels, are scaled down in the browser before they're saved. |

See [Images](/docs/content/images/).

### a11y

| Key | Default | What it does |
|---|---|---|
| `blockPublishOn` | `[]` | Rules whose notes stop a save, such as `['missing-alt']`. In the cloud they stop a publish, not a draft. |
| `backgrounds` | None | The colours your site draws text on, by name, as hex: `{ Page: '#ffffff', Footer: '#1d2433' }`. Colour fields with `contrast` are checked against each. |

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

The rule names are on [Accessibility checks](/docs/site/accessibility/).

### redirects

| Key | Default | What it does |
|---|---|---|
| `native` | Detected | Hosts to write their own redirect rules for: `netlify`, `cloudflare`, `vercel`, `apache` or `nginx`. Netlify, Cloudflare Pages and Vercel are detected from the build environment; name `apache` or `nginx` yourself. |

Every host also gets an HTML redirect page at each old address. See [Hosting](/docs/site/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:

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

| Key | What it does |
|---|---|
| `label` | The tag's name in the studio. |
| `description` | Help text for the tag. |
| `summary` | The attribute whose value the block's header shows: "Callout · Warning". |
| `attributes` | Per attribute: `label`, `description`, `labels` for each value, and `widget`, such as `'color'`. |

### 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.

```ts
import { z } from 'astro/zod';
import { defineConfig } from 'vespercms/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() }) },
    },
  },
});
```

| Key | Default | What it does |
|---|---|---|
| `label` | The component's name | Its name in the studio. |
| `description` | None | Help text. |
| `summary` | None | The prop the block's header shows. |
| `children` | `false` | `true` shows a frame whose content stays editable. |
| `inline` | `false` | `true` inserts the component inside a line of text. |
| `props` | None | A Zod object schema for its props. Saves check props with it, as your site does. |

See [Markdoc and MDX](/docs/content/markdoc-and-mdx/).

### widgets

Your own React controls for fields:

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

| Key | Default | What it does |
|---|---|---|
| `component` | Required | Loads the component, which receives `WidgetProps` from `vespercms/config`. |
| `accepts` | Any field | Which fields it may be used on. |
| `match` | None | Claims fields on its own. Without it, a field asks for the widget with `.meta({ widget: 'store-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](/docs/content/fields/).
