---
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://docs.lightdrop.cloud/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' })
```

## 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>
        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 }
      </code>
    </td>
    
    <td>
      always an image; <code>
        image()
      </code>
      
       without a default can be <code>
        null
      </code>
    </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
    </td>
  </tr>
</tbody>
</table>

Every field takes `{ label }` for the editor. 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.

`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 site on the left, the form as a sidebar on the right.
- **Phones:** the site fills the screen and the form is a sheet over it, dragged up or down by its
handle.

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.

Lists can be reordered, and images come from the camera or the gallery. The editor speaks English
and German, after the browser's language.

### 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.
- **Deployed:** saving writes the app's database, and images go to the app's bucket. 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.
- `GET /api/_cms/schema`: the pages and their fields. Public.
- `POST /api/_cms/images`: uploads an image (`multipart/form-data`, field `file`).


## Sitemap

See the full [sitemap](https://docs.lightdrop.cloud/sitemap.md) for all pages.
