Plugins that need an operator-facing interface — a browsable list, a config panel, a settings page — contribute a Vue IIFE bundle to the host SPA via the apps() hook. The UI is shipped as a separate Composer package and the PHP plugin pulls it in by default so a single composer require gets both halves.

When to ship one

A frontend bundle is overkill for plugins that only need server-side behaviour (a tool, an LLM driver, a migration). Reach for one when:

• An operator needs to browse or filter records the plugin produced (media assets, calendar events, emails, …).
• The plugin exposes multi-step configuration that doesn’t fit a single settings key.
• You want previews of generated artefacts (images, audio, …).

If you only need a settings form with a few inputs and no list, previews, or multi-step config, declare #[ToolSetting] attributes on your tools instead — Architecture: settings live on the tool — and skip the second package entirely.

The two-package pattern

A plugin with a UI is two Composer packages, each with its own type:

Package	type	Lands in	Job
spora-ai/spora-plugin-foo	spora-plugin	plugins/foo/	PHP entry point, manifest, tools, migrations
spora-ai/spora-plugin-foo-frontend	spora-plugin-frontend	public/plugins/foo/	Vue 3 IIFE bundle + Tailwind-compiled CSS

The split exists so the host SPA can lazy-load the bundle at /plugins/foo/main.js without a build step at install time (production ships pre-built assets via SporaPluginFrontendInstaller), and so a plugin author can swap or fork the bundle without touching PHP.

Wiring the apps() hook

The PHP plugin’s entry-point contributes the App class via apps():

public function apps(): array
{
    return [
        FooApp::class,
    ];
}

FooApp implements Spora\Apps\VueAppInterface and tells the host SPA which file to load:

use Spora\Apps\VueAppInterface;

final class FooApp implements VueAppInterface
{
    public function name(): string { return 'foo'; }
    public function displayName(): string { return 'Foo'; }
    public function description(): string { return 'Browse, filter, and manage foo records.'; }
    public function icon(): string { return 'puzzle'; }
    public function accent(): string { return 'emerald'; }

    /** File inside the frontend package's `frontend/` directory. */
    public function entry(): string { return 'main.js'; }
}

The host SPA fetches entry() via /plugins/foo/main.js at runtime and mounts the bundle’s exported mount(target, hostContext) into the app slot. See spora-frontend/src/apps/registry.ts for the full mount contract.

mount() may be sync or async — the registry awaits a thenable return. Returning a Promise is the recommended shape when the app has to settle a route before it renders, because when mount() runs the address bar may already hold a deep link: mounting first and navigating after puts a frame of the home page in front of the operator and lets any layout-level URL normalisation run against a route that has not settled. Await router.isReady() before app.mount() in that case. unmount() may be called at any time afterwards, including before an async mount() has resolved.

Tile accent (accent)

accent() declares the colour token the host SPA applies to your app’s tile in the navbar drawer. The frontend keeps a small palette of named tokens — violet, amber, emerald, sky, rose, primary — each backed by a Tailwind gradient pair. Pick the closest match; if a genuinely new colour is needed, add it to both spora-frontend/src/components/navbar/GlobalSheetApps.vue’s tileAccent() map and the accent enum in spora-core/plugin.schema.json in the same change so the SPA doesn’t ship an unstyled accent.

Precedence — AppsController resolves the final token in this order:

1. The PHP accent() method on your App class.

2. The plugin manifest’s accent field (lets a JSON-only plugin skip the PHP class):

   { "slug": "foo", "class": "Spora\\Plugins\\Foo\\FooPlugin", "accent": "emerald" }

3. The default "primary".

Unknown / empty values fall back to "primary" silently — same posture as the icon field’s unknown-name → puzzle resolver. Plugin authors won’t see a crash for a typo, just a neutral tile until they fix it.

Auto-requiring the frontend

The PHP plugin’s composer.json should require the frontend package with a permissive semver range. That way a single composer require spora-ai/spora-plugin-foo pulls in both halves, and operators who want a different frontend version can constrain it in their own composer.json:

"require": {
    "php": "^8.4.1",
    "spora-ai/spora-core": ">=0.7.0 <1.0.0",
    "spora-ai/spora-plugin-foo-frontend": ">=0.1.0 <1.0.0"
}

The >=0.1.0 <1.0.0 shape matches spora-core’s constraint — any 0.x version of the frontend satisfies, leaving room for the frontend to ship 0.2, 0.3, … without breaking this dependency. Operators override with a stricter constraint:

composer require spora-ai/spora-plugin-foo-frontend:^0.2

Composer uses the stricter of the two constraints, so this upgrades the frontend in place while leaving the PHP plugin untouched. The PHP plugin stays plugin-agnostic — it knows the frontend by package name, not by inlining any of its bundle code.

Declaring the install destination slug

The SporaPluginFrontendInstaller (in spora-installer) reads the destination slug from composer.json#extra.spora-plugin-slug on the frontend package. The slug must match the parent PHP plugin’s plugin.json#slug exactly — the host SPA’s /api/v1/apps response (emitted by AppsController) carries that slug, and the SPA lazy-loads /plugins/<slug>/main.js. A mismatch leaves the bundle unreachable and the SPA renders “Plugin uninstalled”.

{
  "name": "spora-ai/spora-plugin-foo-frontend",
  "extra": {
    "spora-plugin-slug": "foo"
  }
}

• The value MUST equal the parent PHP plugin’s plugin.json#slug (which must match ^[a-z0-9][a-z0-9_-]*$ per spora-core/plugin.schema.json).
• The installer fails loud at install time (InvalidArgumentException) if the field is missing or empty — there is no fallback to the package short name. A silent fallback produced exactly this bug in pre-v0.2.0 installer releases (the frontend package’s short name spora-plugin-foo-frontend did not match the parent plugin’s slug foo, so the SPA requested a path the installer had not populated).
• Slugs containing /, \, or .. are rejected at install time as path-traversal protection under the public web root — belt-and-braces against hand-rolled composer.json overrides, since the schema regex already excludes those characters from well-formed slugs.
• This contract shipped in spora-installer v0.2.0 (companion PR spora-ai/spora-installer#10). Frontend packages whose install previously routed by short name will throw on the next composer update after the operator upgrades the installer — declare the slug before upgrading.

Canonical worked example: spora-plugin-media-archive-frontend declares "spora-plugin-slug": "media-archive" to match spora-plugin-media-archive’s plugin.json#slug (companion PR spora-ai/spora-plugin-media-archive-frontend#9, merged).

Sharing Vue + Pinia with the host SPA

The host SPA already has Vue and Pinia running. Bundling your own copies would create two reactive systems and break shared state (the plugin couldn’t read the host’s auth/theme store, and a createApp() call from one Vue couldn’t mount a component compiled against the other). The build therefore keeps Vue and Pinia external and reads them off the host’s globals at evaluation time.

The host publishes the references in its main.ts after app.mount(...):

import * as Vue from 'vue'
import * as Pinia from 'pinia'
;(window as unknown as { Vue: typeof Vue }).Vue = Vue
;(window as unknown as { Pinia: typeof Pinia }).Pinia = Pinia

Your vite.config.ts then maps the externals to those globals so Rollup emits the right call site:

export default defineConfig({
  build: {
    lib: { entry: 'src/main.ts', formats: ['iife'], name: 'SporaAppFoo' },
    rollupOptions: {
      external: ['vue', 'pinia'],
      output: {
        // Property access resolves at evaluation time against the
        // host's already-published globals. Without this the default
        // IIFE wrapper passes bare identifiers (`})(Vue, Pinia);`)
        // and the bundle throws `Vue is not defined` when loaded
        // via `import('/plugins/<slug>/main.js')`.
        globals: {
          vue: 'window.Vue',
          pinia: 'window.Pinia',
        },
      },
    },
  },
})

The resulting frontend/main.js ends with })(window.Vue, window.Pinia);. Plugins don’t share the host’s Pinia state — they instantiate a local one inside their own mount() — but they read Vue.createApp and Pinia.createPinia off the host’s modules, which is what makes identity equality work.

If you skip the output.globals block, the build still succeeds but the runtime throws Vue is not defined the moment the host dynamic-imports your bundle. The canonical worked example is spora-plugin-media-archive-frontend’s vite.config.ts.

Isolating plugin CSS

A plugin’s frontend/style.css is loaded into the same document as the host SPA. In production the host adds a <link> to the document head; in the proxied Vite workflow the plugin’s CSS module injects a <style> element that remains loaded for the module’s lifetime. A plugin stylesheet is therefore document-global, even though Vue renders the plugin into a dedicated slot.

Unscoped Tailwind builds can override host utilities with the same specificity. For example, a plugin’s later .hidden rule can beat the host’s lg:flex sidebar rule, while its .flex rule can reveal a desktop-hidden mobile control. Every Tailwind-based plugin frontend must provide all three parts of the isolation contract below.

1. Disable plugin preflight and scope utilities

The host already owns document-level resets. Disable preflight and use Tailwind’s selector-based important option to place generated utilities beneath a plugin-owned root:

import type { Config } from 'tailwindcss'

export default {
  content: ['./index.html', './src/**/*.{vue,js,ts,jsx,tsx}'],
  corePlugins: { preflight: false },
  important: '#spora-plugin-foo',
  // theme, plugins, and other settings…
} satisfies Config

Use #spora-plugin-<slug>, where <slug> matches the app and install-destination slug. Do not use important: true: that keeps selectors global and strengthens collisions with the host instead of containing them.

2. Omit the base layer

The plugin’s Tailwind entry only needs components and utilities:

@tailwind components;
@tailwind utilities;

Omitting @tailwind base makes ownership explicit in addition to corePlugins.preflight: false enforcing it in configuration.

3. Render the matching scope root

Wrap the plugin UI in one stable outer element with the matching ID:

<template>
  <div id="spora-plugin-foo">
    <FooPage />
  </div>
</template>

Selector-based important emits descendant selectors such as #spora-plugin-foo .flex. Keep the scope wrapper itself free of Tailwind utility classes and put layout utilities on descendants. Add a mount or component test that asserts the root exists, and inspect the production build to confirm it contains scoped selectors but no naked .hidden or .flex rules.

This setting only scopes utilities generated by Tailwind. Review handwritten global selectors and third-party CSS imports separately; they still share the host document. The canonical spora-plugin-media-archive-frontend uses this complete pattern.

Publishing sequencing

The frontend must be tagged and on Packagist before the PHP plugin’s CI can resolve the require. Recommended sequence:

1. Tag and publish the frontend first (vX.Y.Z from main, push tag, Packagist webhook fires within minutes).
2. Then — or in a separate PR — bump the PHP plugin’s require to the new constraint.
3. Tag and publish the PHP plugin.

Trying to require an unpublished frontend leaves the PHP plugin’s CI red (composer install can’t resolve). If you’re scaffolding both packages at once, publish the frontend first.

Reference

• PHP plugin: spora-ai/spora-plugin-media-archive — the canonical worked example. The apps() hook contributes MediaArchiveApp, which implements VueAppInterface with entry(): 'main.js'.
• Frontend bundle: spora-ai/spora-plugin-media-archive-frontend — Vite builds a single SporaAppMediaArchive IIFE into frontend/main.js + frontend/style.css, which SporaPluginFrontendInstaller copies into public/plugins/media-archive/ on composer install.

Local dev for the UI

The frontend package has its own Vite dev server; for the full HMR pipeline (host + plugin + plugin’s UI) see Local plugin development — the 3-terminal walkthrough covers running both halves with hot reload.

What’s next

• Distribution — when you have working code on main and want to ship

Edit this page on GitHub

Contributors: Fabian Graßl

Previous pageMigrations

Next pageAgent templates