Develop a plugin and see it live — the golden path

The one thing that matters: author a map plugin, run one build, and see it live on the platform. This page THREADS the existing docs into that read-order — it does not duplicate them. Follow the six steps; each links to the doc that teaches that piece in depth. Brand-neutral: any team on any platform inherits this same path.

The path at a glance

   author            build             publish            see it live
 plugin-designs/  →  bun run build  →  merge to catalog  →  https://<platform>/plugin-assets/…
   (one folder)      (one step)        (the runbook)        (a tab, an iframe, a <script>)

Everything you build is a compiled Vue custom element — one folder → one bundle → one <tag>. A static HTML page is never a plugin (it can only be iframed). See reference.md for the capability model.

Step 1 — Understand the 5 capabilities (30 sec)

A plugin is one of five tiers, simplest → most composable: single-element → prop-table → monolithic → nested-element SPA → nested-SPA (app-shell). You declare the tier in <bundle>.meta.json ({"type": …}) for the composite tiers. Read reference.md §capabilities; imitate the nearest reference plugin in plugin-designs/.

Step 2 — Author the plugin (the 4-file pattern)

In plugin-designs/<your-plugin>/ create exactly four files (imitate the nearest reference plugin, never author a plugin as a page):

File	What it is
`<your-plugin>.vue`	the root Vue SFC — your plugin's UI (styles are shadow-scoped automatically)
`index.js`	`defineCustomElement(RootVue)` → `customElements.define('<your-tag>', El)` — register ONLY your own tag
`index.html`	the staging entry page that mounts `<your-tag>` (required — the build fails without it)
`<your-plugin>.meta.json`	for composite tiers, declare `{"type": "<machine key>", "composes": […], "label": "…"}`

plugin-designs/ is your FREE ZONE — build freely here. Only contribute a component to the shared library/ (@map) if it is genuinely reusable + parameterized — a library edit reaches every plugin, so it's a HIGH BAR (see reference.md §governance). Full walkthrough: tutorial.md.

Step 3 — Build (one step)

From doxa-maps-plugin-studio/:

bun run build      # discovers plugin-designs/*, bundles each, writes public/doxa-maps/<plugin>/<plugin>.js

Exit 0 + all DX guards PASS + inline-parse-check PASS = a good build. Your plugin now exists as a real custom-element bundle under public/doxa-maps/<your-plugin>/, with a standalone leaf page and a manifest entry. Recipes: how-to.md.

Step 4 — Publish to the live catalog

The platform serves from the catalog repo (platform/mfe-index), NOT from where you develop. Publishing = merging your built bundles into the catalog. The tested procedure, in one block:

# 1. clone the catalog fresh (fetch-first, never force)
git clone --depth 1 <catalog-repo-url> /tmp/catalog
# 2. merge your built bundles into its doxa-maps subtree (--delete mirrors removals)
rsync -a --delete public/doxa-maps/ /tmp/catalog/app/doxa-maps/
# 3. VERIFY every manifest bundle's <name>/<name>.js resolves BEFORE push; confirm the diff is scoped
#    to app/doxa-maps only (never touch a sibling team's bundles)
# 4. commit (product-only message) + push to the catalog's main branch (no force)

The platform serves the catalog directly, so a pushed change is live at once — verify at the URL in Step 5. (The fuller runbook with every gotcha lives in the project's deploy-cycle notes; the block above is the load-bearing sequence.)

(The end-state is the Forgejo CI build-gate — push source, CI builds + publishes automatically. Until a runner is registered, the runbook is the manual path. Same build:unlocked seam.)

Step 5 — See it live (the 5 deployment methods)

Your one element deploys five ways (only an element supports all five — a page supports iframe only):

#	Method	How	Status today
1	iframe	point an `<iframe>` at the plugin's leaf page	✅ proven
3	JavaScript embed	`<script src=".../<plugin>.js">` + `<your-tag>` (SRI-hashed)	✅ proven
2	mobile	`bun run phone` (Capacitor) — build step, no new code	🔶 built, not shot
4	WordPress plugin	the `wordpress/doxa-maps-embed/` PHP wrapper emits the embed snippet	🔶 built, not shot
5	desktop (Tauri)	front-end → desktop app	⬜ aspirational

Say "proven" ONLY for 1 & 3. Verify at https://<platform>/plugin-assets/doxa-maps/<plugin>/<plugin>/index.html. Done = the live site shows it, not a green build.

Step 6 — Surface it (make it discoverable)

A plugin reachable only by direct URL isn't really "seen live." To put it where users navigate, add it as a tab in the cap-5 SPA (plugin-designs/doxa-maps-spa/ — a TAB_DEFS entry + a NAV_MODEL row), then rebuild + republish. Now it's a tab in the flagship app.

That's the whole path: author in plugin-designs/ → bun run build → publish via the runbook → see it live → surface it as a tab. Deep dives: tutorial.md · how-to.md · reference.md · why.md.

5.3 KiB Raw Blame History