Reference

Editor extensions

Blocks, components, Build a block, channels, history, the site view, site settings, the Design panel and the command palette are all extensions. Each is two small files: one for the editor server and one for the page.

An extension has a server half, src/extensions/<name>.js, and a browser half, editor/ext-<name>.js. The server loads every file in src/extensions/ when it starts. The editor loads every ext-*.js file on every page.

The server half

Export an async setup(ctx) that returns what the extension adds:

export async function setup(ctx) {
  return {
    // Answer a request. Return true if you answered it.
    async handle(req, res, url) {
      if (url.pathname !== '/__verso/word-count') return false;
      const page = ctx.renderUrl(url.searchParams.get('url') || '/');
      const words = page.html.replace(/<[^>]*>/g, ' ').split(/\s+/).filter(Boolean).length;
      ctx.sendJSON(res, 200, { ok: true, words });
      return true;
    },
    // Extra properties merged into the editor's data for each page.
    editorData(site, page, template) {
      return { wordCountReady: true };
    },
  };
}

handle is called for each request the editor’s own routes don’t answer, in file-name order, until one returns true. Keep your routes under /__verso/. Whatever editorData returns is merged into the data the page’s editor receives.

What ctx holds

PropertyWhat it is
rootThe site’s folder
broadcast(event)Sends an event to every open editor page
writtenA Map of files Verso wrote itself, by relative path, so the file watcher ignores them. Add to it with hash() when you write a file
hash(data)The hash written expects
relPath(file)A path relative to the site, with forward slashes
send, sendJSONWrite a response: sendJSON(res, status, body)
readBody, readRawRead a request’s JSON body, or its raw bytes
compile({ reload })Recompile the CSS
renderUrl(url)Render a page as the editor would, returning { status, html }
css, cssErrorThe current stylesheet, and the error from the last compile, if any

The browser half

Export init(verso). It runs once on every page the editor opens, after the editor itself.

export function init(verso) {
  verso.menuItems.push({
    label: 'Word count',
    icon: '<svg …></svg>',
    run: async () => {
      const res = await fetch(`/__verso/word-count?url=${encodeURIComponent(verso.data.url)}`);
      const { words } = await res.json();
      verso.toast(`${words} words on this page`);
    },
  });
}

What verso holds

PropertyWhat it is
rootThe editor’s shadow root. Put your interface here, so the page’s styles can’t reach it
dataThe page’s editor data: its URL, fields, values, templates, pages and anything extensions added
valuesThe page’s current field values
queue(change), flush()Queue a change to the page ({ fields: { name: value } }, or a title, description or date) and save it
toast(message, kind, action)Show a short message. Pass 'error' as the kind for a problem, and { label, run } as the action for a button like Undo
menuItemsPush { label, icon, run } to add to the page menu and the command palette
paletteItemsPush { label, run } to add to the command palette only. Create it first: verso.paletteItems = verso.paletteItems || []
addBarButton({ id, title, svg, onClick })Add a button to the editor’s bar. Below md the bar has no room, so the button is offered in the page menu instead, on its own
settingsSections, openSettings()Push { html, bind } to add a section to Page settings: html() returns its markup and bind(panel) wires it up. openSettings() opens the panel
show(el), hide(el), esc(s), icon(name)Small helpers
refreshStatus(), reload(), flash(el)Update the publish status, reload the page when it’s safe to, or outline an element for a moment to show where something landed
ui(classes)Marks a class string for the editor’s own Elevate build

Extensions can offer things to each other on verso too. The builder sets verso.builder.open(name), which opens a block in Build a block.

Styling an extension

The editor is styled with Elevate too, from its own tokens. Write every class string as ui("…"), so Verso’s build can find it, then run npm run build:ui in the Verso folder to compile the editor’s stylesheet. A class that isn’t in that build has no styles.