@navelcloud/nuxt-core

Nuxt Core

Application-level Nuxt layer for Navel Cloud sites and applications.

Installation

npm install @navelcloud/nuxt-core

Extend the package from the consuming Nuxt application:

export default defineNuxtConfig({
  extends: ['@navelcloud/nuxt-core'],
})

@navelcloud/nuxt-core extends @navelcloud/api-client and owns shared application runtime behavior, including API/auth state, module access, tenant bootstrap, i18n, runtime theme values, and the visual site editor bridge.

Local translation fallbacks

Templates can keep their own default copy without reintroducing i18n configuration. Put JSON files in the consuming application's root i18n/locales directory:

i18n/locales/en.json
i18n/locales/nl.json
i18n/locales/de.json

Resolution order is package defaults, then the local template file, then the runtime translation dictionary returned by the API. Later layers override earlier layers while unrelated nested keys are retained.

Runtime theme values

useTheme() loads site-specific values from the API using the current site hostname. Values live outside the deployment, so changing them does not require a build or redeploy.

<script setup>
const theme = useTheme()
const heroImage = computed(() => theme.image('home.hero.image', '/images/default-hero.jpg'))
</script>

<template>
  <img
    :src="heroImage"
    alt=""
    v-site-editor="{
      source: 'theme',
      type: 'image',
      key: 'home.hero.image',
      label: 'Hero image',
      original: '/images/default-hero.jpg',
    }"
  >
</template>

Management applications that extend the layer but are not tenant site templates can disable the runtime theme request with runtimeConfig.public.siteThemeEnabled = false.

Theme-owned appearance controls

A site theme can declare the appearance controls exposed by the management Theme Editor through runtimeConfig.public.siteThemeEditor. The management application renders this metadata generically; color keys, available schemes, select options, and palettes remain owned by the theme.

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      siteThemeEnabled: true,
      siteThemeEditor: {
        scheme: {
          key: 'colors.scheme',
          label: 'Color scheme',
          default: 'light',
          options: [
            { value: 'light', label: 'Light' },
            { value: 'dark', label: 'Dark' },
          ],
        },
        colors: [
          { key: 'colors.background', label: 'Background', default: '#ffffff' },
          {
            key: 'theme.primary',
            label: 'Primary',
            type: 'select',
            default: 'blue',
            options: [
              { value: 'blue', label: 'Blue' },
              { value: 'violet', label: 'Violet' },
            ],
          },
        ],
        palettes: [
          {
            id: 'clean',
            name: 'Clean',
            scheme: 'light',
            swatches: ['#ffffff', '#2563eb', '#171717'],
            values: {
              'colors.background': '#ffffff',
              'theme.primary': 'blue',
            },
          },
        ],
      },
    },
  },
})

scheme is optional. colors fields default to a native color input and can use type: 'select' with theme-owned options. Palette scheme values optionally scope a palette to one color scheme. swatches are optional display colors for palettes whose actual values are semantic names rather than CSS colors.

All declared values use the normal useTheme().value(key, fallback) runtime path. The editor preview bridge temporarily overlays values through setPreviewValues() and persisted values continue to use the existing site-theme API.

Site editor

Translations rendered through $t() are automatically exposed when a site is opened with ?site_editor=1. The package keeps the existing navel:site-editor:translation message and also emits the generic navel:site-editor:select message.

v-site-editor and useSiteEditor().attributes() carry only field metadata (source, type, key, label, original). The management application decides which editor UI belongs to a field type. Theme image updates can be applied immediately by posting navel:site-editor:refresh-theme back to the preview iframe.

Resource-backed theme fields

Theme components can expose resource selections through the same site-editor contract. The theme only declares the resource type and the theme key; the management application owns the selector UI and resource lookup. The key is theme-specific, but the editor type is shared across every theme.

Supported management editor resource types currently include calendar, collection, and form.

<script setup>
const theme = useTheme()
const calendarId = computed(() => theme.value('booking.calendar_id', ''))
const collection = computed(() => theme.value('journal.collection', 'news'))
const form = computed(() => theme.value('contact.form', 'contact'))
</script>

<template>
  <BookingCalendar
    v-site-editor="{
      source: 'theme',
      type: 'calendar',
      key: 'booking.calendar_id',
      label: 'Booking calendar',
      original: '',
    }"
    :calendar-id="calendarId"
  />

  <Journal
    v-site-editor="{
      source: 'theme',
      type: 'collection',
      key: 'journal.collection',
      label: 'Journal collection',
      original: 'news',
    }"
    :collection="collection"
  />

  <ContactForm
    v-site-editor="{
      source: 'theme',
      type: 'form',
      key: 'contact.form',
      label: 'Contact form',
      original: 'contact',
    }"
    :form="form"
  />
</template>

The same metadata can be applied without a directive when a component needs to forward attributes:

const siteEditor = useSiteEditor()

const editorAttributes = siteEditor.resourceAttributes(
  'collection',
  'journal.collection',
  'news',
  'Journal collection',
)

app.navel.cloud resolves the resource type to the tenant API and renders a select list. The theme does not contain resource-listing or admin-editor logic.

Visual page layouts

The site builder shares two UI components through this Nuxt layer: SitePageLayout (renders registered Vue blocks during SSR) and SiteLayoutEditor (edits a JSON page layout inside a management dashboard). Individual themes register their built Vue components and expose a serializable siteBuilderBlocks list in runtimeConfig.public for the editor. The iframe preview sends this list to the management editor with navel:site-layout:config. Only registered component types can render.

A page layout uses { "schemaVersion": 1, "sections": [{ "id": "hero-1", "type": "hero", "props": { "title": "Welcome" } }] }. The Laravel Workers API holds separate draft and published layouts. useSiteContent().fetchPage(path) fetches published content (including path = '' for the homepage), while fetchPreview(pageId, token) fetches an authorized short-lived draft. Template implementations should render their original page if no published layout exists, and should only use the preview endpoint in a noindex editor route.

Native theme sections

SitePageLayout can render the original theme's own markup through named slots, without extracting API workflows from the page or replacing the visual design:

<SitePageLayout :layout="layout" :registry="{}">
  <template #hero>
    <section class="theme-hero">Original hero</section>
  </template>
  <template #services>
    <ModuleView module="appointments">
      <section class="theme-services">Original booking services</section>
    </ModuleView>
  </template>
</SitePageLayout>

A theme declares its existing section types through runtimeConfig.public.siteBuilderBlocks, and its current order through siteBuilderDefaultLayout (the same versioned JSON layout schema as published pages). The iframe navel:site-layout:config message can include defaultLayout so SiteLayoutEditor can initialize a new unsaved draft, when initializeFromTheme is true. Existing, intentionally saved drafts are never overwritten by that initialization. The normal public page uses the published layout when present and otherwise renders the theme's defaults.

Slots keep all existing page-scoped variables, event bindings, translations and module conditions. Unrecognized block types are not rendered. Existing component-registry blocks continue working unchanged. Do not send reactive Vue proxies directly through postMessage; the editor serializes layouts before sending.