Extensions

An extension is a Go plugin (a .so file) that the engine opens at boot when the project’s engine.yaml names it. It adds template globals and filters, HTTP routes, commands, the asset helpers’ resolver and a dev server to the project, without your needing the engine’s source: you build it against one small module, github.com/wrux/meridian-extend, which uses the Go standard library only.

Use an extension when templates and configuration cannot express what you need. For logic behind a declared endpoint, a project plugin runs out of process and is easier to deploy; for wiring Vite, use the first-party vite extension.

A minimal extensionCopy Anchor Link

// shout.go
package main

import (
	"context"
	"strings"

	extend "github.com/wrux/meridian-extend"
)

type shout struct{}

func (shout) Manifest() extend.Manifest {
	return extend.Manifest{ID: "shout", Name: "Shout", Version: "1.0.0"}
}

// Register declares the filter, so engine-dmo check admits it in templates.
func (shout) Register(r extend.Registrar) error {
	return r.Filter("shout", "value|shout: the value in capitals")
}

// Init attaches the filter's function once the engine is running.
func (shout) Init(_ context.Context, h extend.Host) error {
	return h.Filter("shout", func(_ extend.Render, in, _ extend.Value) (any, error) {
		return strings.ToUpper(in.String()), nil
	})
}

// Extension is the symbol the engine looks up.
var Extension extend.Extension = shout{}

func main() {}

Build it for the engine it will load into (see Building for the exact rules), put the file in the project and name it:

go build -trimpath -buildmode=plugin -o extensions/shout.so .

# config/engine.yaml
extensions:
  - extensions/shout.so

<h2>{{ entry.title|shout }}</h2>

engine-dmo check --project . now admits |shout, and engine-dmo version --project . lists shout among the modules.

How the engine uses an extensionCopy Anchor Link

This is the whole path from your source to a template calling your filter: one build on your side, then four stages in every engine process that names the file.

flowchart TD
  src["your extension<br/>(package main)"] -->|"go build -buildmode=plugin"| so["greet.so"]
  so --> yaml["engine.yaml<br/>extensions: [extensions/greet.so]"]
  yaml --> cgo{"engine built<br/>with cgo?"}
  cgo -->|no| refuse["refused: pure Go build"]
  cgo -->|yes| info{"build info matches<br/>the engine's?"}
  info -->|no| mismatch["refused, naming<br/>the difference"]
  info -->|yes| reg["Load and Register<br/>(every command, check included)"]
  reg -->|"serve only"| init["Init: attach functions,<br/>mount routes"]
  init -->|"a declared name<br/>not attached"| stop["boot stops"]
  init --> call["Call: each template use<br/>of a global or filter"]

The interfacesCopy Anchor Link

Your plugin’s main package exports one variable, Extension, of type extend.Extension. You implement Extension and, optionally, Initer. Every other interface below is implemented by the engine; you call it and never implement it. The engine may add methods to those interfaces in a minor release of the module.

Extension and IniterCopy Anchor Link

type Extension interface {
	Manifest() Manifest
	Register(r Registrar) error
}

type Initer interface {
	Init(ctx context.Context, h Host) error
}

ManifestCopy Anchor Link

RegistrarCopy Anchor Link

What Register receives.

HostCopy Anchor Link

What Init receives.

Functions you writeCopy Anchor Link

// Called for every call a template makes.
type GlobalFunc func(r Render, args Args) (any, error)

// in is the value the filter is applied to; arg IsNil when the template wrote none.
type FilterFunc func(r Render, in, arg Value) (any, error)

// ok false leaves the bundle to the engine's own fallback.
type AssetsFunc func(r Render, req AssetRequest) (markup HTML, ok bool)

// Returns the zero DevServer, and no error, when there is nothing to serve.
type DevServerFunc func(ctx context.Context, d Dev) (DevServer, error)

A global or filter returns a string, a number, a bool, []any, []string, map[string]any, extend.HTML, an extend.Value, or nil. A string is escaped where the template prints it. extend.HTML is printed unescaped: return it only for markup you built from escaped parts. An error fails the render with the global or filter named (greeting(): ..., |shout: ...).

RenderCopy Anchor Link

The page render a function runs in.

SiteCopy Anchor Link

Args and ValueCopy Anchor Link

Args are a call’s arguments: positional ones, then keywords written name=value.

Value is a template value as your function receives it: IsNil, IsString, IsNumber, IsInteger, IsBool, IsList, IsMap, IsTrue (its truth as {% if %} reads it), String() (as a template prints it, "" when nil), Int(), Float(), Bool() (false unless it is a boolean), Len() (of a string, list or map), Index(i) (a list’s item, nil out of range) and Interface() (the Go value: strings, numbers, booleans, []any and map[string]any are what they say; any other type is the engine’s own and opaque to you).

AssetsCopy Anchor Link

The asset helpers (assets.css('main'), assets.js('main'), assets.js('legacy', false), preload()) ask your resolver for each bundle:

Return ok false to leave a bundle to the engine, which prints css/<name>.css or js/<name>.js under public/ for css and js, and nothing for preload. The frontend build describes the helpers.

Dev serverCopy Anchor Link

CommandsCopy Anchor Link

Run receives a CommandContext:

A complete extensionCopy Anchor Link

This extension declares a global that takes a keyword and reads the page’s locale, a filter with an optional argument, an asset resolver for one bundle, a dev server and a command.

// greet.go
package main

import (
	"context"
	"flag"
	"fmt"
	"html"
	"net"
	"net/http"
	"strings"

	extend "github.com/wrux/meridian-extend"
)

type greet struct{}

var Extension extend.Extension = greet{}

func (greet) Manifest() extend.Manifest {
	return extend.Manifest{ID: "greet", Name: "Greetings", Version: "0.1.0"}
}

func (greet) Register(r extend.Registrar) error {
	if err := r.Global("greeting", "greeting(name, punct='.'): a greeting for name in the page's language, ending in punct", "punct"); err != nil {
		return err
	}
	if err := r.Filter("shout", "value|shout or value|shout:'!': the value in capitals, with the argument after it"); err != nil {
		return err
	}
	if err := r.DevServer(devServer); err != nil {
		return err
	}
	return r.Command(extend.Command{
		Path:  "greet hello",
		Short: "Print a greeting, to show an extension's command",
		Flags: func(fs *flag.FlagSet) { fs.String("name", "world", "who to greet") },
		Run: func(_ context.Context, c extend.CommandContext) error {
			_, err := fmt.Fprintf(c.Stdout(), "Hello, %s, from %s\n", c.Flags().Lookup("name").Value.String(), c.ProjectDir())
			return err
		},
	})
}

func (greet) Init(_ context.Context, h extend.Host) error {
	if err := h.Global("greeting", greeting); err != nil {
		return err
	}
	if err := h.Assets(assets); err != nil {
		return err
	}
	return h.Filter("shout", func(_ extend.Render, in, arg extend.Value) (any, error) {
		return strings.ToUpper(in.String()) + arg.String(), nil
	})
}

var hello = map[string]string{"en": "Hello", "ja": "こんにちは", "th": "สวัสดี"}

func greeting(r extend.Render, a extend.Args) (any, error) {
	word, ok := hello[strings.SplitN(r.Locale(), "-", 2)[0]]
	if !ok {
		word = hello["en"]
	}
	punct := "."
	if p, ok := a.Keyword("punct"); ok {
		punct = p.String()
	}
	return word + ", " + a.At(0).String() + punct, nil
}

// assets resolves the greet bundle and leaves every other one to the engine.
func assets(r extend.Render, req extend.AssetRequest) (extend.HTML, bool) {
	if req.Bundle != "greet" || req.Kind != "js" {
		return "", false
	}
	var b strings.Builder
	if r.Once("greet-client") {
		b.WriteString(`<script type="module" src="` + html.EscapeString(r.Site().PathPrefix+"/greet/client.js") + `"></script>`)
	}
	b.WriteString(`<script type="module" src="` + html.EscapeString(r.Site().PathPrefix+"/greet/"+r.Site().Key+".js") + `"></script>`)
	return extend.HTML(b.String()), true
}

// devServer serves a greeting on a free loopback port under serve --dev.
func devServer(_ context.Context, d extend.Dev) (extend.DevServer, error) {
	l, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		return extend.DevServer{}, err
	}
	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		fmt.Fprintln(w, "hello from the greet dev server")
	})}
	go func() { _ = srv.Serve(l) }()
	d.Log.Info("greet dev server", "addr", l.Addr().String())
	return extend.DevServer{Origin: "http://" + l.Addr().String(), Stop: func() { _ = srv.Close() }}, nil
}

func main() {}

In a template:

<p>{{ greeting("visitor", punct="!") }}</p>
<h2>{{ entry.title|shout:"!" }}</h2>
{{ assets.js('greet') }}

On an en-GB page the first line prints Hello, visitor!; on a ja-JP page, こんにちは, visitor!. From the shell:

engine-dmo greet hello --name Sian --project .

Mounting a routeCopy Anchor Link

A route is mounted in Init and secures itself:

func (greet) Init(_ context.Context, h extend.Host) error {
	h.Route("GET /greet/health", http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		_, _ = w.Write([]byte(`{"ok":true}`))
	}))
	// attach globals and filters as above
	return nil
}

BuildingCopy Anchor Link

A Go plugin shares the Go runtime and every common package with the program that opens it, so it loads only into the exact build it was made for. The engine reads your plugin’s build information before it opens it and refuses any difference, naming it and saying what to change. What your plugin must match:

engine-dmo version

meridian v0.8.0 (vips) go1.27.3
  bundle dmo: modules ai directory forms crm ...
  extensions: built with go1.27.3 linux/amd64, cgo, -trimpath, meridian-extend v0.0.0-00010101000000-000000000000

The values above are an example; read your own engine’s.

engine-dmo version --json gives the same under extensions: supported, go_version, os, arch, level, cgo, trimpath, meridian_extend and modules (every module the engine links, by path and version).

The module fileCopy Anchor Link

// go.mod
module example.com/greet

go 1.26.0

toolchain go1.27.3

require github.com/wrux/meridian-extend v0.0.0-00010101000000-000000000000

replace github.com/wrux/meridian-extend => ../meridian-extend

Require meridian-extend at exactly the version engine-dmo version prints. While the module is not published to a Go module proxy, that version is the zero pseudo-version shown above and your go.mod points a replace directive at your copy of the module’s source.

Keep your extension’s own dependencies to the standard library where you can: any module the engine also links must be required at the engine’s version, or the plugin will not open.

The build commandCopy Anchor Link

For the container image (linux/amd64), build with the official Go image of the engine’s toolchain:

docker run --rm --platform linux/amd64 -v "$PWD":/src -w /src \
  -e GOWORK=off -e CGO_ENABLED=1 golang:1.27.3-trixie \
  go build -trimpath -buildmode=plugin -o greet.so .

For an engine binary on your own machine, with the same Go version installed:

GOWORK=off CGO_ENABLED=1 go build -trimpath -buildmode=plugin -o greet.so .

If your replace points outside the directory you mount into the container, mount that directory too.

Which engines load extensionsCopy Anchor Link

Extensions load only in an engine built with cgo, on Linux, macOS or FreeBSD. The -vips container image is one; an engine built without cgo refuses every extension (this engine is a pure Go build, which cannot load extensions: run the -vips image, a cgo build). Windows cannot load Go plugins. See Container images.

Rebuild for every engine releaseCopy Anchor Link

There is no compatibility window between releases: a plugin built for one engine build opens in that build only. A new engine release may change the Go toolchain, the meridian-extend version or a shared module. Rebuild every extension against each release before you deploy it, and run engine-dmo check with the new binary: it opens every extension and reports a mismatch at its line in engine.yaml.

Naming extensions in engine.yamlCopy Anchor Link

# config/engine.yaml
extensions:
  - vite                     # a first-party extension, by name
  - extensions/greet.so      # your own, by path relative to the project

Each file loads once per process, in the order listed, then extensions are registered in the order their Requires allow. Every problem across the list is reported together, each at its line.

ErrorsCopy Anchor Link

The loader’s messages, each reported by engine-dmo check at the entry’s line in engine.yaml with error code MRD-1006, and by serve before it boots:

SecurityCopy Anchor Link

An extension runs inside the engine process with the engine’s privileges, its memory and its environment, secrets included. It is trusted code, like the engine itself: review it as you would the engine, build it yourself from source you control, and never load a .so you did not build. A route it mounts has no authentication unless the handler adds it.