Frontend Plugins

Choose the extension points

A plugin can register any combination of four capabilities. Use the pieces your integration needs; the server continues to own the HTML returned by content invocations.

Examples include rich text editing, autocomplete, barcode readers, file-selection SDKs, charts, maps, accessibility helpers, and adapters around existing jQuery widgets. The registry owns installation and lifecycle; application services still handle validation, authorization, persistence, and HTML rendering.

These are application runtime plugins. AI agent skills and marketplace packaging have their own guide. Server-side library discovery is also a separate registration surface.

Load and install a plugin

The consuming application loads the runtime and plugin assets, supplies options, and calls Heimdall.use. Keep the core runtime synchronous in the document head before the registration module so installation precedes DOMContentLoaded boot.

<link rel="stylesheet" href="/_content/Company.Editor/css/editor.css">
<script src="/_content/HeimdallFramework.Web/heimdall-bundle.min.js"></script>
<script type="module" src="/js/install-plugins.js"></script>

// wwwroot/js/install-plugins.js in the application
import editorPlugin from "/_content/Company.Editor/js/editor-plugin.js";

if (Heimdall.pluginApiVersion !== 1)
    throw new Error("This integration requires Heimdall plugin API v1.");

Heimdall.use(editorPlugin, { commitKey: "Enter" });

Availability: this page documents plugin API v1 in the current framework source. Use matching Server, Rendering, and Web builds that contain these APIs. A previously installed runtime can expose Heimdall.invoke while still lacking the plugin registry; check pluginApiVersion when integrating an older application.

• An RCL serves wwwroot assets through /_content/{PackageId}/...; an application can instead serve a module from its own wwwroot.
• A bundler can import the same plugin object. Classic script distributions can expose their object on a package-owned global, then install it explicitly.
• Keep one application Heimdall runtime. A plugin package uses that runtime and does not bundle a second instance.
• NuGet installation, AddCompanyEditor, and invocation assembly scanning do not load JavaScript/CSS or call Heimdall.use.
• Heimdall.use does not fetch scripts, styles, or dependencies. The application controls loading, CSP, dependency order, and cache/version deployment.
• Late installation initializes existing matching elements, but skipped commands are not replayed. Install before initial load invocations need a plugin payload or command.

Complete example: editor module to usable feature

This small editor supports Ctrl+Enter and a normal Save button through the same payload reader. The server trims the submitted text, returns a status fragment, and sends a registered command to update the textarea. Reset is a static invocation; Save uses a scoped instance with options.

Library layout: EditorRegistration.cs, EditorPanel.cs, wwwroot/js/editor-plugin.js, and wwwroot/css/editor.css. Use a Razor Class Library with PackageId Company.Editor and a reference to the matching HeimdallFramework.Server package. Server references HeimdallFramework.Rendering transitively.

Company.Editor/
  EditorRegistration.cs
  EditorPanel.cs
  wwwroot/
    js/editor-plugin.js
    css/editor.css

ConsumingApp/
  Program.cs
  wwwroot/js/install-plugins.js

// Company.Editor/wwwroot/js/editor-plugin.js
export default {
    id: "company.editor",
    version: "1.0.0",
    pluginApiVersion: 1,

    install(api, options = {}) {
        const commitKey = options.commitKey ?? "Enter";
        if (typeof commitKey !== "string" || !commitKey)
            throw new TypeError("commitKey must be a non-empty string.");

        api.behaviors.register({
            name: "keyboard",
            selector: "textarea[data-company-editor]",
            mount(element, { signal }) {
                element.addEventListener("keydown", event => {
                    if (!(event instanceof KeyboardEvent) ||
                        event.key !== commitKey || !event.ctrlKey) return;
                    event.preventDefault();
                    element.dispatchEvent(new CustomEvent(
                        "company-editor-commit", { bubbles: true }));
                }, { signal });
            }
        });

        api.triggers.register({
            name: "commit",
            events: ["company-editor-commit"]
        });

        api.payloads.register({
            name: "document",
            read({ element }) {
                const editor = element instanceof HTMLTextAreaElement
                    ? element
                    : element.closest("[data-company-editor-host]")
                        ?.querySelector("textarea[data-company-editor]");
                if (!(editor instanceof HTMLTextAreaElement))
                    throw new TypeError("The editor payload source is missing.");
                return { text: editor.value };
            }
        });

        api.commands.register({
            name: "set-text",
            /** @returns {args is { text: string }} */
            validate: args => typeof args === "object" && args !== null &&
                "text" in args && typeof args.text === "string",
            handle({ element, args, signal }) {
                if (!(element instanceof HTMLTextAreaElement))
                    throw new TypeError("An editor command needs a textarea.");
                if (!signal.aborted) element.value = args.text;
            }
        });
    }
};

The behavior owns its keyboard listener through the mount signal. The trigger declares which event starts an invocation. The reader also accepts a button inside the editor host, so the built-in click path shares the same data contract. The command validates its JSON arguments before touching the textarea.

// Company.Editor/EditorRegistration.cs
using Heimdall.Server;
using Microsoft.Extensions.DependencyInjection;

namespace Company.Editor;

public sealed class CompanyEditorMarker;

public sealed class EditorOptions
{
    public string SavedLabel { get; set; } = "Saved";
}

public static class EditorRegistration
{
    public static IServiceCollection AddCompanyEditor(
        this IServiceCollection services,
        Action<EditorOptions>? configure = null)
    {
        services.AddHeimdallInvocationAssembly<CompanyEditorMarker>();
        services.AddScoped<EditorPanel.Invocations>();
        services.AddOptions<EditorOptions>();
        if (configure is not null) services.Configure(configure);
        return services;
    }
}

// Company.Editor/EditorPanel.cs
using Heimdall.Server;
using Heimdall.Server.Rendering;
using Microsoft.AspNetCore.Html;
using Microsoft.Extensions.Options;

namespace Company.Editor;

public sealed class EditorDocument
{
    public string? Text { get; set; }
}

public static class EditorPanel
{
    public static IHtmlContent Render()
        => FluentHtml.Section(panel => panel
            .Attr("data-company-editor-host", "")
            .Label(label => label.For("company-editor").Text("Document"))
            .TextArea(editor =>
            {
                editor.Id("company-editor")
                    .Attr("data-company-editor", "true")
                    .Class("company-editor-input");
                editor.Heimdall()
                    .OnPluginTrigger("company.editor.commit", "company.editor.save")
                    .PayloadFromPlugin("company.editor.document")
                    .Target("#editor-status")
                    .SyncReplace("company-editor");
            })
            .Button(button =>
            {
                button.Type("button").Text("Save");
                button.Heimdall().OnClick("company.editor.save")
                    .PayloadFromPlugin("company.editor.document")
                    .Target("#editor-status")
                    .SyncReplace("company-editor");
            })
            .Button(button =>
            {
                button.Type("button").Text("Reset");
                button.Heimdall().OnClick("company.editor.reset")
                    .PayloadEmptyObject().Target("#editor-status")
                    .SyncReplace("company-editor");
            })
            .Div(status => status.Id("editor-status")
                .Attr("role", "status").Text("No changes saved")));

    public sealed class Invocations(IOptions<EditorOptions> options)
    {
        [ContentInvocation("company.editor.save")]
        public IHtmlContent Save(EditorDocument document)
        {
            var text = (document.Text ?? "").Trim();
            return FluentHtml.Fragment(fragment =>
            {
                fragment.Add(FluentHtml.Span(status => status
                    .Text($"{options.Value.SavedLabel}: {text.Length} characters")));
                fragment.Heimdall().PluginCommand(
                    "company.editor.set-text", new { Text = text }, "#company-editor");
            });
        }
    }

    public static class StaticInvocations
    {
        [ContentInvocation("company.editor.reset")]
        public static IHtmlContent Reset()
            => FluentHtml.Fragment(fragment =>
            {
                fragment.Add(FluentHtml.Span(status => status.Text("Editor reset")));
                fragment.Heimdall().PluginCommand(
                    "company.editor.set-text", new { Text = "" }, "#company-editor");
            });
    }
}

The host calls the package extension, configures its own Heimdall services, maps a page, and loads the module as shown above. This example normalizes input and reports its length; add your persistence service inside Save when implementing a stored document.

// Consuming application: Program.cs
using Company.Editor;
using Heimdall.Server;
using Heimdall.Server.Rendering;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAntiforgery();
builder.Services.AddCompanyEditor(options =>
    options.SavedLabel = "Document saved");
builder.Services.AddHeimdall();

var app = builder.Build();
app.UseAntiforgery();
app.MapStaticAssets();
app.UseStaticFiles();
app.UseHeimdall();

app.MapHeimdallPage("/editor", () => FluentHtml.Fragment(fragment => fragment
    .Raw("<!DOCTYPE html>")
    .HtmlTag(html => html.Lang("en")
        .Head(head => head
            .Meta(meta => meta.Attr("charset", "utf-8"))
            .Meta(meta => meta.Name("viewport")
                .ContentAttr("width=device-width, initial-scale=1"))
            .Title(title => title.Text("Company editor"))
            .Link(link => link.Attr("rel", "stylesheet")
                .Href("/_content/Company.Editor/css/editor.css"))
            .Script(script => script
                .Src("/_content/HeimdallFramework.Web/heimdall-bundle.min.js"))
            .Script(script => script.Type("module")
                .Src("/js/install-plugins.js")))
        .Body(body => body.Add(EditorPanel.Render())))));

app.Run();

/* Company.Editor/wwwroot/css/editor.css */
.company-editor-input {
    display: block;
    width: 100%;
    min-height: 8rem;
    margin-block: 0.5rem;
}

The example renders one editor with fixed IDs. A multi-instance component should generate stable per-instance host/target IDs, keep widget instances in a WeakMap, and resolve payloads within that instance's host. Plugin and extension names identify capabilities; DOM IDs identify individual rendered instances.

Plugin identity, versions, options, and namespaces

A plugin is an object with a stable identity and a synchronous install function. Its package version and the frontend SDK version describe different contracts.

export default {
    id: "company.editor",
    version: "1.0.0",
    pluginApiVersion: 1,
    requires: ["company.foundation"],
    install(api, options) {
        // Register capabilities and cleanup synchronously.
    }
};

Local extension names are qualified automatically. Registering set-text in company.editor creates company.editor.set-text. Different capability registries may use the same local name; duplicate names within one registry and conflicting trigger attributes are rejected.

Heimdall passes the host's options to the plugin. Validate them and apply your own defaults. They are not implicitly merged into Heimdall.config, cloned into a framework options model, or interpreted by the server. Server EditorOptions and JavaScript commitKey options remain separate contracts.

Installation, dependencies, rollback, and removal

Installation stages registrations and commits them only after install succeeds. This keeps a failed registration from leaving a partially installed registry.

const options = { commitKey: "Enter" };
Heimdall.use(editorPlugin, options);
Heimdall.use(editorPlugin, options); // Exact references: no-op.

console.table(Heimdall.plugins.list());
const removed = Heimdall.plugins.remove("company.editor");

• Heimdall.use returns Heimdall for chaining. Repeating the identical plugin object and options reference is idempotent.
• A different plugin object or options reference under an installed ID throws instead of silently replacing a live plugin.
• Missing dependencies, unsupported plugin API versions, duplicate registrations, invalid descriptors, and an async install fail installation.
• Rollback aborts api.signal, invokes registered plugin cleanup, and discards staged registry entries. Arbitrary external side effects still require your cleanup.
• Registrations and api.onDispose close when install returns. Async setup belongs to a behavior's mount rather than a later register call.
• Removal aborts the plugin scope, disposes active mounts and subscriptions, and unregisters capabilities. Unknown IDs return false.
• Removing a plugin that an installed dependent still requires throws. Remove dependents first, then their dependency.
• The same plugin can be installed again after removal; it starts a fresh active lifetime.

install(api, options) {
    window.addEventListener("resize", onResize, { signal: api.signal });
    const timer = setInterval(checkExternalState, 5000);
    api.onDispose(() => clearInterval(timer));
    // A returned function is an additional plugin-wide cleanup.
    return () => releaseSharedResources();
}

Prefer declarative triggers for rendered interactions. api.invoke is available for narrow programmatic integrations after installation commits, and rejects after plugin removal. It supports the normal invocation options, antiforgery, headers, synchronization, and results.

Managed behaviors and async readiness

Behaviors connect a selector to an element lifetime. Use them to initialize third-party widgets and own the work that must stop when those elements leave the document.

api.behaviors.register({
    name: "widget",
    selector: "[data-company-widget]",
    observedAttributes: ["data-widget-options"],
    async mount(element, { signal }) {
        // createWidget is supplied by your widget integration.
        const widget = await createWidget(element, { signal });
        return {
            update() {
                widget.configure(element.getAttribute("data-widget-options"));
            },
            dispose() { widget.destroy(); }
        };
    }
});

Heimdall waits for behavior readiness before initial load invocations consume plugin payloads and before a targeted command runs against its relevant behavior subtree. Keep data readers synchronous by completing asynchronous preparation in mount.

An observed change calls update when available; an instance without update is disposed and remounted. Update is synchronous. A failed or timed-out mount aborts its signal and reports a diagnostic. Failed mounts are not retried on every unrelated DOM mutation; change observed options or remove/restore the marker to request another mount.

Cleanup that arrives from an async mount after removal still runs. Pass the signal into cooperative widget APIs and check it around your own awaits. An aborted signal cannot undo effects that third-party JavaScript already performed.

DOM moves, swaps, observation, and disposal

A behavior instance follows an active element match. The runtime preserves existing instances when the same DOM element stays active and disposes ownership when it leaves.

// If your application disables normal DOM observation:
Heimdall.dispose(container); // Before external removal.
container.remove();

host.append(newContent);
Heimdall.boot(host);         // After external insertion.

Heimdall's own inserted roots initialize even when observeDom is false. Its automatic observer covers the main document; shadow roots and other documents require their own integration. Choose selectors whose membership reflects ownership, rather than transient hover/focus state or unrelated descendants.

Custom DOM triggers

A custom trigger declares an event-to-invocation mapping and enters the same request pipeline as a built-in click, input, or submit.

api.triggers.register({
    name: "commit",
    events: ["company-editor-commit"],
    preventDefault: true,
    debounceMs: 150,
    filter: ({ event }) => event !== null
});

<textarea data-company-editor
  heimdall-content-company-editor-commit="company.editor.save"
  heimdall-payload-from="plugin:company.editor.document"
  heimdall-content-target="#editor-status"
  heimdall-sync="replace"
  heimdall-sync-group="company-editor"></textarea>
<div id="editor-status"></div>

Default attributes replace dots in the qualified name with hyphens. If you configure an explicit custom attribute, emit that exact attribute with an ordinary HTML attribute helper; OnPluginTrigger emits the default mapping.

Custom triggers share scope/self/closest resolution, ignore boundaries, prevent-default, debounce, disabled checks, request sync, headers, antiforgery, payload selection, targeting, swaps, and lifecycle events. Ignore lists use the qualified trigger name or *. Multiple event types may be declared on one rendered element. Trigger adapters do not need a separate fetch implementation.

SDK subscriptions and explicit emissions

Use subscribe when an integration has a callback API rather than a native DOM event. Its cleanup owns that subscription; a removed subscription cannot start more requests.

api.triggers.register({
    name: "scan",
    subscribe({ element, emit, signal }) {
        // scanner is provided by your integration.
        const unsubscribe = scanner.subscribe(value => {
            if (!signal.aborted)
                void emit(null, { payload: { code: value } });
        });
        return unsubscribe;
    }
});

Use the supplied signal for listeners or cooperative SDK work. The returned cleanup should release external callbacks, timers, or subscriptions even if the SDK does not accept AbortSignal. Handle any additional promise rejection from your own integration code; use Heimdall diagnostics for managed trigger failures.

Independent payload readers and queue snapshots

A payload source belongs to a named data-reading capability, so the same reader works with a custom trigger, built-in click, submit, or load.

api.payloads.register({
    name: "document",
    timing: "trigger", // Default; or "execution".
    read({ element, options }) {
        return { text: readPreparedEditorText(element) };
    }
});

read receives the source element and installation options. It returns JSON-serializable data or FormData synchronously. Promise-returning readers are rejected; perform async setup in a behavior. The example helper readPreparedEditorText represents your integration's synchronous reader.

// C#: the same reader can be attached to a built-in trigger.
button.Heimdall().OnClick("company.editor.save")
    .PayloadFromPlugin("company.editor.document")
    .Target("#editor-status");

Keep payloads small and validate them server-side. A plugin reader does not change the server's one-payload binding rule or turn browser widget state into trusted domain state.

Registered response command handlers

A command is a qualified name plus JSON arguments and an optional DOM target. The browser resolves only a handler already registered by a loaded plugin.

api.commands.register({
    name: "set-text",
    /** @returns {args is { text: string }} */
    validate: args => typeof args === "object" && args !== null &&
        "text" in args && typeof args.text === "string",
    async handle({ element, args, signal }) {
        if (!(element instanceof HTMLTextAreaElement))
            throw new TypeError("An editor target is required.");
        await prepareEditor(element, signal);
        if (signal.aborted) return;
        element.value = args.text;
    }
});

prepareEditor is integration-owned asynchronous work. Check signal after awaits before performing effects. A command's validate function must return true to accept its arguments; throwing, false, or malformed JSON skips that command and reports a diagnostic.

No target means one call with element null. A target selector uses the first matching element; allTargets applies to each match. Selectors resolve when the command executes, so an after command can target newly inserted HTML. Missing, invalid, or disconnected targets are reported and skipped. Related target behavior readiness completes before the handler runs.

C# helpers and wire format

Use encoded helpers so command arguments remain data and HTML text/attribute encoding is correct. JSON argument property names use web defaults.

using Heimdall.Server.Rendering;

fragment.Heimdall().PluginCommand(
    name: "company.editor.set-text",
    args: new { Text = "Saved content" },
    targetSelector: "#company-editor",
    timing: HeimdallHtml.PluginCommandTiming.After,
    allTargets: false);

// Static form; suitable for an invocation or Bifrost payload.
var command = HeimdallHtml.PluginCommand(
    "company.editor.set-text", new { Text = "Saved content" },
    "#company-editor");

// The other markup helpers:
HeimdallHtml.OnPluginTrigger("company.editor.commit", "company.editor.save");
HeimdallHtml.PayloadFromPlugin("company.editor.document");

<heimdall-command
  name="company.editor.set-text"
  args='{"text":"Saved content"}'
  target="#company-editor"
  timing="after"></heimdall-command>

Omit target for a global command; use allTargets: true for every selector match. C# rejects allTargets without a selector and rejects blank selectors. Use PluginCommandTiming.Before for the before phase. Fully qualified lowercase extension names are required.

This response directive is separate from browser-native command/commandfor attributes and from JsInvokeVoidBefore/After. Plugin commands provide registered handlers with argument validation, awaited completion, lifetime signals, and managed target readiness. Existing JavaScript void directives retain their original completion semantics.

Response order, aborts, redirects, and cancellation

A command participates in a response phase. Within each phase, commands preserve response order and each handler's completion is awaited.

Directives are removed before normal HTML insertion. Cancellation and timeouts bound Heimdall's wait and abort the signal; they cannot forcibly stop JavaScript that ignores the signal. Design asynchronous handlers to cooperate and make server operations independently safe against repeated user requests.

Deliver commands over Bifrost

The same encoded command helper can be published as HTML over a normal authorized Bifrost topic. A plugin package does not need a second client transport.

await bifrost.PublishAsync(
    topic: "orders",
    content: HeimdallHtml.PluginCommand(
        "company.editor.set-text",
        new { Text = "Updated by the server" },
        targetSelector: "#company-editor"),
    ttl: TimeSpan.FromSeconds(10),
    ct: cancellationToken);

<div heimdall-sse-topic="orders" heimdall-sse-swap="none"></div>

• Messages with plugin commands are serialized per subscription, including later messages while an asynchronous command is pending.
• Pause, disconnect, element disposal, or plugin removal cancels relevant pending processing.
• The pending-message queue is bounded by pluginSseQueueLimit. Overflow reports sse-command-queue-full and closes the subscription with plugin-command-queue-full.
• Delivery is not an exactly-once guarantee. Heimdall does not automatically retry a command handler.
• Authorize topics using the normal Bifrost policy/handler model; plugin command registration is not an authorization boundary.

Diagnostics and execution limits

Installation errors throw. Runtime mount, update, disposal, trigger, subscription, payload, and command failures are surfaced through heimdall:plugin-error.

document.addEventListener("heimdall:plugin-error", event => {
    const { pluginId, extension, phase, code, invocationId } = event.detail;
    reportPluginFailure({ pluginId, extension, phase, code, invocationId });
});

The detail also includes error and available sourceElement context. Keep payloads, secrets, editor text, and user identifiers out of routine telemetry. A command error does not rewrite the HTTP status or undo DOM effects that already completed.

Registered handlers receive structured data. The runtime does not evaluate server-supplied JavaScript source. A plugin script itself has normal page authority, so application owners choose and review their plugin dependencies.

TypeScript, JavaScript authoring, and the public SDK

The shipped heimdall-plugins.d.ts file defines HeimdallPlugin, descriptors, contexts, command validation, invocation options/results, registry metadata, and browser globals.

/_content/HeimdallFramework.Web/heimdall-plugins.d.ts

Reference that declaration artifact from your TypeScript setup or vendor the matching declaration file into your development types directory. It is a type file, not a script to load into the page. Pin it with the runtime version your package supports.

import type { HeimdallPlugin } from "./types/heimdall-plugins";

type EditorOptions = { commitKey?: string };
const editor: HeimdallPlugin<EditorOptions> = {
    id: "company.editor",
    pluginApiVersion: 1,
    install(api, options) {
        // Descriptor callbacks receive contextual SDK types.
    }
};
export default editor;

/** @type {import("./types/heimdall-plugins").HeimdallPlugin<{ commitKey?: string }>} */
const editorPlugin = {
    id: "company.editor",
    pluginApiVersion: 1,
    install(api, options = {}) { /* ... */ }
};

Use a type-predicate validate function when TypeScript should narrow command args for its handler. Private _build modules are implementation details and are not supported authoring imports. Additions within plugin API v1 are additive; incompatible signatures or lifecycle changes require a new plugin API major and an explicit migration.

Production integration tests and troubleshooting

Verify a plugin from a separate consuming project, using public assets and public APIs. Exercise the actual widget's lifecycle and the same browser/server boundary your users will run.

• Install with explicit options; test duplicate IDs, dependency order, rollback, and removal/reinstallation.
• Exercise initial document boot, repeated boot, moves, multiple inserted roots, append, inner/outer replacement, and external removals.
• Test async readiness, observed-attribute updates, a removed pending mount, timeouts, and resource cleanup.
• Verify native/custom/subscription triggers, built-in triggers with plugin readers, queue snapshot timing, and missing readers.
• Exercise real assembly discovery, scoped DI across requests, antiforgery, auth headers, authorization, and cancellation.
• Verify before/after commands, multiple targets, failures, redirects, aborts, stale response suppression, and Bifrost ordering.
• Run against both readable and minified runtime bundles; collect unexpected browser errors and plugin diagnostics.

In a matching framework checkout, Heimdall.E2E.TestPlugin is a standalone RCL consumed by Heimdall.E2E. Its /e2e/plugins workbench exposes manual controls and lifecycle/command/error logs; ?runtime=debug selects the readable runtime. It tests real HTTP and Bifrost connections.

# From Heimdall.E2E in the framework checkout:
npm run test:plugins

# From Heimdall.Web:
npm run test:types

Related guides

Use the server and runtime references alongside this page when building a reusable package.