---
title: "Editable content"
description: "Let a site's owner change texts, images and lists on the live site with @wervt/cms, without a redeploy."
canonical_url: "https://wervt.app/guides/cms"
---
# Editable content

> Let a site's owner change texts, images and lists on the live site with @wervt/cms, without a redeploy.

`@wervt/cms` makes parts of a Nuxt site editable by the people who own it: a café's opening hours,
a hero photo, the dishes on a menu. You describe what can be edited in `cms/`, the page reads it
with `useCms`, and the owner changes it at `/_cms` on the live site. Edits show right away; nothing
is rebuilt.

```bash
pnpm add @wervt/cms @wervt/nuxt
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wervt/cms'], // loads @wervt/nuxt with its database and ablage for uploads
})
```

## Describe a page

Each file in `cms/` defines one page: its key, its fields with their defaults, and optionally a
label for the editor and the `path` where it shows on the site.

```ts [cms/home.ts]
import { defineCmsPage, image, list, richText, text } from '@wervt/cms/schema'

export default defineCmsPage(
  'home',
  {
    hero: {
      title: text('Welcome to Café Rosa'),
      image: image('/hero.jpg', { label: 'Photo' }), // a file in public/
    },
    intro: richText('Fresh from the oven **every morning**.'),
    hours: list({ day: text(), time: text() }, [
      { day: 'Mon–Fri', time: '8–18' },
      { day: 'Sat', time: '9–14' },
    ]),
  },
  { label: 'Home', path: '/' },
)
```

```vue [app/pages/index.vue]
<script setup lang="ts">
const home = useCms('home')
</script>

<template>
  <h1>{{ home.hero.title }}</h1>
  <img
    :src="home.hero.image.src"
    :srcset="home.hero.image.srcset"
    sizes="100vw"
    :alt="home.hero.image.alt"
  />
  <CmsRichText :value="home.intro" />
  <ul>
    <li v-for="row in home.hours" :key="row.day">{{ row.day }}: {{ row.time }}</li>
  </ul>
</template>
```

`useCms('home')` is typed from `cms/home.ts`. The page renders its defaults until someone saves,
so it works before anyone edits it. Pages must render on the server, not be prerendered, or edits
only show after the next deploy.

Content that isn't a page of its own, such as a footer, is a page without a `path`:

```ts [cms/footer.ts]
export default defineCmsPage('footer', { note: text('© Café Rosa') }, { label: 'Footer' })
```

## Collections

For content that comes in any number, like news, events or jobs, a collection describes one item.
The owner adds and deletes items in the editor; each has its own address.

```ts [cms/news.ts]
import { date, defineCmsCollection, image, richText, text } from '@wervt/cms/schema'

export default defineCmsCollection(
  'news',
  {
    title: text('', { required: true }),
    date: date(),
    image: image('/hero.jpg'),
    body: richText(),
  },
  { label: 'News', path: '/news/[slug]', sort: '-date' },
)
```

```vue [app/pages/news/index.vue]
<script setup lang="ts">
const news = await useCmsCollection('news')
</script>

<template>
  <ul>
    <li v-for="post in news" :key="post.slug">
      <NuxtLink :to="post.path">{{ post.title }}</NuxtLink>
    </li>
  </ul>
</template>
```

```vue [app/pages/news/[slug].vue]
<script setup lang="ts">
const route = useRoute()
const post = await useCmsItem('news', () => String(route.params.slug))
if (!post.value) throw createError({ status: 404, fatal: true })
</script>

<template>
  <h1>{{ post.title }}</h1>
  <CmsRichText :value="post.body" />
</template>
```

Each item has its fields plus `slug`, and `path` when the collection has one. Await both
composables so the 404 check sees the item and a page navigated to shows its list at once.

- **slug:** the item's name in the address (`summer-sale`), suggested from its title when the
owner creates it. It can't change afterwards, so links to the item keep working.
- **path:** where an item shows on the site, with `[slug]` in it. Without one the items are only
listed, like the entries of a timeline.
- **sort:** a field, `-` first for newest first; items without a value come last. Without it the
items are sorted by their title.
- **titleField:** the `text()` field the editor names items by; the first `text()` field by
default.

A collection's key is one word, and a page key can't start with it: the collection `news` owns
every `news/<slug>` key. Deleting an item takes it off the site at once.

## Fields

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      The page gets
    </th>
    
    <th>
      Notes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text('…')
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        { multiline: true }
      </code>
      
       for several lines
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        richText('…')
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
      
       (Markdown)
    </td>
    
    <td>
      shown with <code>
        <CmsRichText :value>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        toggle(true)
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number(12.5)
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      always a number; <code>
        number()
      </code>
      
       without a default can be <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        select(['a', 'b'], 'a')
      </code>
    </td>
    
    <td>
      <code>
        'a' | 'b'
      </code>
    </td>
    
    <td>
      one of the options; <code>
        { value, label }
      </code>
      
       names one in the editor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        date('2026-08-05')
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        YYYY-MM-DD
      </code>
      
      , or with <code>
        { time: true }
      </code>
      
       <code>
        YYYY-MM-DDTHH:mm
      </code>
      
      ; <code>
        date()
      </code>
      
       can be <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        link({ label, href })
      </code>
    </td>
    
    <td>
      <code>
        { label, href }
      </code>
    </td>
    
    <td>
      <code>
        href
      </code>
      
      : a path, <code>
        #…
      </code>
      
      , <code>
        https://
      </code>
      
      , <code>
        mailto:
      </code>
      
       or <code>
        tel:
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        image('/a.jpg')
      </code>
    </td>
    
    <td>
      <code>
        { src, srcset?, alt, position? }
      </code>
    </td>
    
    <td>
      always an image; <code>
        image()
      </code>
      
       without a default can be <code>
        null
      </code>
      
      ; <code>
        { focus: true }
      </code>
      
       see <a href="#cropped-images">
        Cropped images
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list({ …fields }, [ … ])
      </code>
    </td>
    
    <td>
      an array of items
    </td>
    
    <td>
      saved as a whole; each item gets the fields' defaults
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        { …fields }
      </code>
    </td>
    
    <td>
      an object
    </td>
    
    <td>
      a group of fields shown together, titled by its name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        group({ …fields })
      </code>
    </td>
    
    <td>
      an object
    </td>
    
    <td>
      the same group, with <code>
        { label }
      </code>
      
       for its title
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        seo({ title, description, image })
      </code>
    </td>
    
    <td>
      <code>
        { title, description, image }
      </code>
    </td>
    
    <td>
      the page's search and share texts, see <a href="#search-and-sharing">
        Search and sharing
      </a>
    </td>
  </tr>
</tbody>
</table>

Every field and group takes `{ label }` for the editor and `{ hint }`, a line under it on what
goes in. Keep page keys and field names stable: a renamed field shows its default again. A saved
value that no longer fits its field (it changed from text to a list, say) is ignored and the
default shows, so changing `cms/` never breaks a page.

`text` and `richText` take `{ required: true }` (not empty) and `{ maxLength: 80 }` (characters
as people count them; Markdown formatting counts for `richText`), `link` takes `{ required: true }`
(an address is needed), `number` takes `{ min, max }` and `{ step }` for how far the editor's
buttons move it, and `date` takes `{ min, max }` written like its value. The editor marks such fields, counts characters and refuses to save until
they fit; the API answers `400` with the field's path for a value that doesn't. A field left out of
a `PUT` keeps its default and isn't checked. A rule added later applies to the next save, not to
what is already saved.

```ts
title: text('Café Rosa', {
  label: 'Name',
  hint: 'Shown at the top of every page and in the browser tab.',
  required: true,
  maxLength: 40,
}),
```

A date has no time zone: `date('2026-08-05T18:30', { time: true })` means 18:30 wherever the page
is rendered. Turn it into a `Date` from its parts or with a time appended, never with
`new Date('2026-08-05')`, which is midnight in UTC and the day before west of it:

```ts
const day = new Date(`${cms.value.opening}T00:00`)
day.toLocaleDateString('de-DE', { dateStyle: 'long' }) // 5. August 2026
```

### Cropped images

Where the page crops a picture with `object-cover`, a banner or a round avatar, `{ focus: true }`
lets the owner tap what must stay in view. The editor shows a point on the picture and how it
crops as a square and as a banner. The page gets the point as `position`, ready for
`object-position`; without one it is unset and the browser centers as usual:

```ts
hero: image('/hero.jpg', { label: 'Photo', focus: true }),
```

```vue
<img
  :src="home.hero.src"
  :alt="home.hero.alt"
  class="h-64 w-full object-cover"
  :style="{ objectPosition: home.hero.position }"
/>
```

The point is stored with the image as `focus: { x, y }`, in percent from the top left. A new
upload starts without one.

### Search and sharing

`seo()` adds the page's title, description and share image as fields the owner can edit, in a
section of its own in the editor. `useCmsSeo('home')` on the page turns them into `<title>`,
`description`, Open Graph and Twitter tags, the image as an absolute URL:

```ts
// cms/home.ts
export default defineCmsPage('home', {
  // …
  seo: seo({ description: 'Coffee and cake in Freiburg.', image: '/og.jpg' }),
})
```

```vue
<script setup lang="ts">
const home = useCms('home')
useCmsSeo('home')
</script>
```

A field left empty sets nothing, so the page's own `useHead` title (or the app's) stays until the
owner writes one. Call it on the page the content describes, not in a layout: `useCms` alone never
touches the head, so a footer can read the page's content on every route.

`CmsRichText` renders bold, italic, links, headings and lists. Editors may type anything, so it
keeps raw HTML and `javascript:` or `data:` links as plain text; rendering the Markdown yourself
skips that.

## The editor

The editor is at `/_cms` on the site, made for phones as much as for desktops. It shows the site
next to the form with what's in the form, saved or not:

- **Wide screens:** the form is a sidebar beside the site, on the left by default.
- **Phones:** the site fills the screen and the form is a sheet over it, dragged up or down by its
handle.

The eye button in the form's header hides the preview, so the form gets the whole screen. The `⋮`
menu moves the sidebar to the other side. Each browser keeps these choices; the side a site starts
with is set in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  cms: { editor: { sidebar: 'right' } },
})
```

A menu lists the pages. Pages with a `path` form a tree by their paths, so `/menu/drinks` sits
under `/menu`; pages without one, like the footer, are listed apart as content on every page.
Following a link in the preview opens that page's form. `/_cms?key=<key>` opens one page directly.

Collections are listed in the menu apart from the pages. A collection opens as the list of its
items, with a search once there are more than a few; **New** asks for the title and the slug and
opens the new item's form, which reaches the site with its first save. **Delete** in the `⋮` menu
removes the item open in the form.

Once you opened the editor signed in as an editor, the site shows an **Edit** button in the
bottom corner of every page, in that browser only. It opens the editor on the page you were
looking at. Visitors never see it, and it costs them nothing: the browser remembers the editor's
answer, so the site doesn't ask the server. `cms: { editor: { button: 'right' } }` moves it to the
other corner, `false` turns it off. `/_cms?path=/menu` opens the editor on that page by hand.
**Close the editor** in the `⋮` menu goes back to the page the preview shows.

Lists can be reordered, and images come from the camera or the gallery. A link's address can be
typed or picked from the site's pages: every page without parameters (`/menu`, not
`/menu/[id]`), plus the CMS pages with a `path`, named by their label. The editor speaks English
and German: the site's language (`app.head.htmlAttrs.lang`) when it is one of them, otherwise the
browser's. `cms: { editor: { locale: 'de' } }` sets it.

When someone else saved the page after you opened it, saving doesn't overwrite their edit. The
editor asks instead: load their version and drop your changes, or save yours over theirs.

**Earlier versions** in the `⋮` menu lists the page's last 50 saves, with who saved each and which
fields it changed. Picking one puts it into the form and the preview; saving brings it back.

### The media library

**Media library** at the bottom of the page menu, or in the `⋮` menu, shows every uploaded image, newest
first, with the pages and items that use it. A click on one of them opens its form. Several
images can be uploaded at once, and an image nothing uses can be deleted. One in use can't be:
take it out of every page first. An image in the open form counts as used before you save it.

An image field's **From library** button picks one of these images instead of uploading it again.
The field keeps its alt text, or takes the one the image has elsewhere.

Only saved content counts as a use, not earlier versions: bringing back a version whose image was
deleted since shows it broken. Images under `public/cms/` that the deployed app ships with appear
too, marked as part of the website; they can't be deleted from the editor.

### Who can edit

The app's owner, its members and wervt admins, once signed in at `/_wervt/login`; the editor links
there. In `nuxt dev` it signs you in as the owner. To let others edit, list their addresses (only
confirmed ones count):

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  cms: { editors: 'anna@example.com,ben@example.com' },
})
```

or set `NUXT_CMS_EDITORS` on the deployed app with `wervt env`, which needs no redeploy.

### The editor's look

The editor looks like wervt's dashboard by default. `cms.editor.theme` in `nuxt.config.ts` matches
it to the site: a primary color, the font, the corner radius, light and dark colors and a
stylesheet of your own. The [package README](https://github.com/wervt-app/wervt/tree/main/packages/cms#the-editors-look)
lists every option.

## Where edits are stored

- **nuxt dev:** saving writes `cms/entries.json` in the app, and uploaded images go to
`public/cms/`. Commit both; the deploy ships them. Earlier versions go to
`.data/cms-history.json`, which stays on your machine.
- **Deployed:** saving writes the app's database, and images go to the app's bucket. Earlier
versions are kept there too. The page gets
a signed `src` and a `srcset` from 640 to 2400 px from wervt's image service. The module turns
the database on, so the app needs no `drizzle/` folder for it.

When the file and the database both hold an entry for a key, the newer one wins: deploying an
edited `cms/entries.json` replaces a live edit, and a later live edit wins again.

Uploads take JPEG, PNG, WebP, GIF, AVIF and HEIC (iPhone photos) up to 25 MB; the editor shrinks
photos to 2400 px before sending them. In `nuxt dev`, where images are served as they are, the
limit is 5 MB and HEIC isn't taken.

## API

The editor uses these routes, and so can you:

- `GET /api/_cms/entries/<key>`: the page's values, defaults filled in. Public.
- `PUT /api/_cms/entries/<key>`: saves; the body is the value. Checked against the page's fields,
with a `400` that names the field that doesn't fit. Send `If-Match: "<updatedAt>"` with the
`updatedAt` you read (or `If-None-Match: *` for a page never saved) to save only over that
version: anything newer answers `412` with the current `updatedAt` in `data`. Without either
header the save always wins.
- An item is an entry too, at `<collection>/<slug>`: `PUT` there with `If-None-Match: *` creates
it.
- `DELETE /api/_cms/entries/<collection>/<slug>`: deletes an item. Takes `If-Match` like `PUT`.
Editors only.
- `GET /api/_cms/collections/<key>`: the collection's items in its order, each with `slug`, `path`,
`value` and `updatedAt`. Public.
- `GET /api/_cms/schema`: the pages and collections with their fields. Public.
- `POST /api/_cms/images`: uploads an image (`multipart/form-data`, field `file`).
- `GET /api/_cms/images`: the media library, as `{ images: [...] }` with each image's `value`,
a small `thumb`, `name` (missing for shipped images) and `uses`. Editors only.
- `DELETE /api/_cms/images/<name>`: deletes an upload. `409` with the `uses` in `data` while
saved content uses it, `404` when there is none. Editors only.
- `GET /api/_cms/access`: `200` when the signed-in person may edit, `401` or `403` otherwise.
- `GET /api/_cms/links`: the site's pages a link can point to, as `{ path, label? }`. Editors only.
- `GET /api/_cms/versions/<key>`: the page's saved versions, newest first, with `updatedAt`, `by`
and the fields each `changed`; `?at=<updatedAt>` answers one with its values. Editors only.


## Sitemap

See the full [sitemap](https://wervt.app/sitemap.md) for all pages.
