Frontend build

The engine does not own your frontend build. It serves what is in public/, and its asset helpers print the right <link> and <script> tags for a site’s bundle: plain files when you have no build step, or the content-hashed files a Vite build wrote when the project uses the vite extension. No Node runs in production.

The helpersCopy Anchor Link

<head>
  {{ head() }}
  {{ preload() }}
  {{ assets.css('main') }}
  {{ assets.js('main') }}
  <link rel="icon" href="{{ assets.url('favicon.svg') }}" type="image/svg+xml">
</head>

Each site’s bundle is its own: the same assets.css('main') in a shared layout prints each site’s build.

Without a build stepCopy Anchor Link

With no extension, a bundle name maps to files under public/:

public/
  css/main.css
  js/main.js
  favicon.svg

This is how the bare starter project works, and how a project with a build of its own (any bundler that writes plain file names) can work.

Static filesCopy Anchor Link

Files under public/ are served at their path when no content route matches. They resolve along a chain per site, first match wins:

1. public/<site key>/
2. public/_shared/
3. public/

So public/town/favicon.svg is the town’s icon and public/favicon.svg everyone else’s. Only regular files are served, never directory listings.

To serve another directory, such as uploads from a legacy site, at a URL prefix after the chain, add a mount to engine.yaml:

public:
  mounts:
    - { path: /legacy/, dir: ../legacy-site/files }

path starts and ends with /; dir is relative to the project.

With ViteCopy Anchor Link

The first-party vite extension connects a Vite build to the helpers. Vite writes the files and a manifest; the engine reads the manifest and prints the tags:

flowchart LR
  SRC["src/entries/main.js<br/>CSS and JS"] --> V["vite build"]
  M["engine-dmo assets manifest<br/>(read by meridian(), optional)"] -.-> V
  V --> OUT["public/build/<br/>hashed files"]
  V --> MAN["public/build/.vite/manifest.json"]
  MAN --> EXT["vite extension"]
  EXT --> H["assets.css('main')<br/>assets.js('main'), preload()"]
  H --> P["link and script tags<br/>under /build/"]
  OUT --> P

• assets.css(), assets.js() and preload() read the build’s manifest and print the content-hashed files, under /build/;
• engine-dmo serve --dev starts the project’s Vite dev server as a child process and points the helpers at it, with hot module replacement;
• engine-dmo assets budget and engine-dmo assets unused report on the build.

# config/engine.yaml
extensions:
  - vite

// src/entries/main.js
import '../css/site.css';
import '../js/site.js';

// vite.config.js
import { defineConfig } from 'vite';
import { meridian } from 'vite-plugin-meridian';

export default defineConfig({
  plugins: [meridian()],
  build: { target: 'es2022', cssMinify: true, sourcemap: false },
});

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/build/',
  build: {
    outDir: 'public/build',
    emptyOutDir: true,
    manifest: true,
    rollupOptions: { input: { 'main/main': 'src/entries/main.js' } },
  },
  server: process.env.MERIDIAN_VITE_ORIGIN
    ? { origin: process.env.MERIDIAN_VITE_ORIGIN, strictPort: true }
    : {},
});

npm install
engine-dmo build

What the helpers print from the buildCopy Anchor Link

A bundle the manifest does not know falls back to css/<name>.css and js/<name>.js along the public chain. The manifest is read again when the file changes, so a rebuild needs no restart. The manifest itself is not served.

DevelopmentCopy Anchor Link

engine-dmo serve --dev looks for vite.config.js (or .mjs, .ts, .mts, .cjs, .cts) in the project. With one, and Vite installed in node_modules/.bin/vite, it:

• starts Vite on a free loopback port with --strictPort, passing MERIDIAN_VITE_ORIGIN, MERIDIAN_PROJECT and MERIDIAN_ENGINE in its environment;
• writes Vite’s output into the engine’s log and stops Vite on Ctrl+C;
• prints the Vite client once per page and each entry’s source URL in place of the built files; preload() prints nothing, and assets.css() prints nothing for a script entry, whose CSS the dev server injects;
• widens the development content security policy to admit the dev server’s origin and inline styles (the dev server injects each stylesheet as a <style> element). Only in development.

With a config and no installed Vite, it says so and serves public/ as it is. CSS changes reach the page through Vite’s hot module replacement; with the meridian() plugin, saving a template reloads the whole page.

site.yaml assetsCopy Anchor Link

# config/sites/<key>/site.yaml
assets:
  bundles:
    main: src/entries/town.js
    legacy: src/legacy/town-legacy.js
  budgets:
    css: 60KB
    js: 120KB
    legacy_js: 200KB
  external: false
  manifest: ""

ReportsCopy Anchor Link

engine-dmo render <path> --json lists the assets the rendered page references.

Content security policyCopy Anchor Link

The public site’s policy is server.security.csp in engine.yaml. Each key is a directive, with underscores for hyphens, and each value a list of sources. With no csp block, no policy header is sent.

# config/engine.yaml
server:
  security:
    csp:
      default_src: ["'self'"]
      script_src: ["'self'"]
      style_src: ["'self'"]
      style_src_attr: ["'unsafe-inline'"]
      img_src: ["'self'", "data:", "${MEDIA_CDN_ORIGIN:-}"]
      font_src: ["'self'"]
      connect_src: ["'self'"]
      object_src: ["'none'"]
      base_uri: ["'self'"]
      form_action: ["'self'"]
      frame_ancestors: ["'self'"]

• 'unsafe-inline' and 'unsafe-eval' are refused in script_src and default_src: the engine’s scripts need neither.
• An empty source is dropped, so an unset ${MEDIA_CDN_ORIGIN:-} leaves nothing behind.
• style_src_attr: ["'unsafe-inline'"] lets image placeholders paint (Images); no script can be injected through a style attribute, and templates cannot write one.
• A page that renders a video or a third-party embed widens the policy for that response alone, to let the player’s host frame it.

The engine’s own scripts are files on the site’s origin, added only when a page needs them: the form challenge (/_e/forms.js), the impressions reporter (/_e.js), the video facade (/_mrd-video.js) and the embed facade (/_mrd-embed.js).

No inline scriptCopy Anchor Link

Write behaviour in your bundle, not in the page. engine-dmo check enforces the template side:

Pass data to your script through data-* attributes, or a JSON block, which is data and not executed:

<div id="map" data-lat="{{ entry.location.lat }}" data-lon="{{ entry.location.lon }}"></div>
<script type="application/json" id="map-data">{{ entry.title|json }}</script>

sigmxCopy Anchor Link

The engine’s in-place updates (forms posted in place, fragments, the sigmx.fragment() helper) use sigmx attributes such as data-on:submit. The client is a module your bundle loads. The example projects use the sigmx npm package with its Vite plugins, which scan the templates at build time, bundle only the plugins used and precompile every expression, so the policy can refuse eval:

// vite.config.js
import { sigmxAuto, sigmxPrecompile } from 'sigmx/vite';
const scan = { root: here, include: ['templates', 'src'] };
// plugins: [meridian(), sigmxAuto(scan), sigmxPrecompile(scan)]

// src/js/site.js
import { createSigmx, precompiled } from 'sigmx';
import { plugins } from 'virtual:sigmx-plugins';
import { table } from 'virtual:sigmx-expressions';
import { handlers } from 'vite-plugin-meridian/sigmx';

window.sigmx = createSigmx({
  plugins: [...plugins, ...handlers],
  expressions: precompiled(table, () => () => undefined, (src) => console.warn('not precompiled', src)),
});

vite-plugin-meridian/sigmx carries the handlers the engine’s fragment responses use, so it comes with the plugin and has the same availability. They act on four events the engine sends after a response’s patches: sigmx-focus ({% focus %}, and the error summary of a failed post), sigmx-announce ({% announce %}), sigmx-location ({% location %}) and sigmx-history ({% replaceurl %} and a facet’s new address). Without the handlers those four do nothing on the page; the patches themselves still apply. Every form and link works without sigmx; it is enhancement.

RelatedCopy Anchor Link

• Multisite templates: per-site bundles and component overrides.
• Extensions: what first-party extensions are and how they load.
• Container images: which image carries extensions.