Skip to Content

Overview

The site template is a Next.js 15 application on React 18, running on Node 22 (.nvmrc). Each site’s repository is a fork of it.

It renders pages from configuration held in Visor:

  1. A route reads the page and works out its layout.
  2. The layout renders its placeholders: Header, Main, Left, Right, Footer.
  3. Each placeholder renders its widgets.
  4. Each widget’s component is found by name.
  5. In Visor’s editor, each component’s Client version loads instead, so people can edit it in place.

Layouts and widgets live in the code. Which ones a page uses, and what they say, lives in Visor.

Project structure

    • Layout.tsx
    • Placeholder.tsx
    • Widget.tsx
  • SITE_LAYER.md
  • amplify.yml
  • env.sample

Your site’s places

A site takes template updates over its lifetime. To keep those clean, write only in the places that belong to the site. SITE_LAYER.md in the repository is the full list.

Your site’s placesWhat goes there
components/widgets/site-widgets/Your widgets, with client/ for their Studio versions.
components/layouts/ (outside platform-layouts/)Your layouts, with client/.
components/placeholders/site-placeholders/Your placeholders.
components/form-configuration/fields/site-fields/Your form fields.
app/styles/<your-theme>/Your themes, as new folders.
styles/site/Your widgets’ and layouts’ styles. index.scss here is yours: add one @use line per file.
New route folders under app/Your own routes.
source/Designs to convert. Git-ignored.
.envYour local settings. Git-ignored.

Everything else belongs to the template, including platform-widgets/, platform-layouts/, lib/ and scripts/. Changing those causes conflicts at the next update. A change the template itself needs goes as a merge request to the template repository.

Check your work with:

npm run check:site-layer

Never import styles in app/layout.tsx. Add them to styles/site/index.scss.

Routes

RoutePurpose
/The Home page.
/<path>Any other page, by its full path. Other languages have a prefix, such as /id/about.
/articles/<slug>An item’s own page, for every content type with workflow. See Content Types in Code.
/preview/design-systemThe design system’s guide. Not in the live build.
/api/widgets, /api/layouts, /api/themeWhat the code offers. Visor reads these.
/api/draftHow Visor’s editor opens a draft.

How the template reads content

The website reads content from GoDaaS, Visor’s data service, as a read-only account for this site. All reads go through lib/daas.ts, on the server or at build time. Browser code calls /api/data-sources instead, and it never talks to GoDaaS directly.

If a read fails, the template logs it and renders the page without that data, so a data problem doesn’t crash the site.

See it in Visor

Visor shows the site in its editor in a frame and exchanges messages with it. Widgets and layouts come from /api/widgets and /api/layouts on the preview, so new code appears in Visor after it is merged and the preview rebuilds, or straight away in Developer mode.

Use visorTarget() to send messages to Visor and acceptFromVisor(event.origin) to check them, never "*".

Last updated on