feature: example plugin

Author: lukepolo

.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.git
+.github

.github/workflows/build.yml

@@ -0,0 +1,51 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - "main"
+  workflow_dispatch:
+
+concurrency:
+  group: build
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to GitHub Docker Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository_owner }}/5stack-example-plugin:buildcache
+          cache-to: type=registry,ref=ghcr.io/${{ github.repository_owner }}/5stack-example-plugin:buildcache,mode=max
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/5stack-example-plugin:latest
+            ghcr.io/${{ github.repository_owner }}/5stack-example-plugin:${{ github.sha }}
+      - name: Delete old package versions
+        uses: actions/delete-package-versions@v5
+        with:
+          package-name: 5stack-example-plugin
+          package-type: container
+          min-versions-to-keep: 9
+          ignore-versions: '^buildcache$'

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

Dockerfile

@@ -0,0 +1,14 @@
+# Builds the Module Federation remote (remoteEntry.js + assets) and serves it as
+# static files. There is no backend — a plugin this small is just a web server
+# handing the panel one JS file.
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+EXPOSE 80

README.md

@@ -0,0 +1,77 @@
+# 5stack Plugin — Hello World
+
+The smallest complete [5stack plugin](https://docs.5stack.gg/plugins): a Vue
+Module Federation remote that renders **natively inside the 5stack panel** —
+same sidebar, header, theme, and login. Copy this repo as the starting point for
+your own.
+
+```sh
+npm install
+npm run dev       # standalone preview at :5173 with a fake dev user
+npm run build     # -> dist/
+npm run preview   # serve dist/ at :4173 with CORS, for testing in a real panel
+```
+
+## What makes it a plugin
+
+| File | Role |
+| --- | --- |
+| `src/App.vue` | Your UI. Receives the logged-in `user` as a prop. |
+| `vite.config.ts` | Exposes `./App` as a Federation remote; declares shared singletons. |
+| `public/5stack-plugin.json` | The manifest the panel auto-detects. |
+| `tailwind.config.js` | Pulls in the `@5stack/ui` preset so you inherit 5stack theming. |
+| `src/main.ts` | Standalone dev entry — **not** used when embedded in the panel. |
+
+## Try it against a running panel
+
+```sh
+npm run build && npm run preview
+```
+
+Then in the panel: **Settings → Application → Custom Pages → Add**, paste
+`http://localhost:4173`, hit **Detect**, toggle **Enabled**, and save. Make sure
+the **Custom Pages** master switch is on. Your page appears in the sidebar at
+`/apps/hello`.
+
+`npm run preview` already sends the CORS and `no-store` headers the panel needs.
+When you deploy for real, your own web server must do the same — see
+[Deploying](https://docs.5stack.gg/plugins/deploying).
+
+## Renaming it
+
+Federation scopes share one flat global namespace across every plugin an
+operator installs, so `hello` will collide — pick something specific:
+
+| Rename | In |
+| --- | --- |
+| `name: "hello"` | `vite.config.ts` |
+| `"scope": "hello"` | `public/5stack-plugin.json` (must equal the above) |
+| `"slug": "hello"` | `public/5stack-plugin.json` (your URL: `/apps/<slug>`) |
+| `[data-hello-plugin]` | `tailwind.config.js` and `src/App.vue` (must match) |
+
+## Two things that are easy to get wrong
+
+**Version lockstep.** Every package in `shared` is `requiredVersion: false`, so a
+version that disagrees with the panel's does not error — it silently loads a
+second copy and breaks reactivity. Pin the same versions the panel uses.
+
+**Style scoping.** This plugin's CSS is injected at runtime *after* the panel's,
+so unscoped utilities would override host chrome. `important:
+"[data-hello-plugin]"` in `tailwind.config.js` scopes every utility under the
+wrapper in `App.vue`. Keep both in sync, and prefer named theme tokens over
+arbitrary values like `min-h-[60vh]`.
+
+## Docs
+
+Full guide: **https://docs.5stack.gg/plugins**
+
+- [Getting Started](https://docs.5stack.gg/plugins/getting-started)
+- [The Manifest](https://docs.5stack.gg/plugins/manifest)
+- [Module Federation](https://docs.5stack.gg/plugins/module-federation)
+- [Styling](https://docs.5stack.gg/plugins/styling)
+- [Components](https://docs.5stack.gg/plugins/components)
+- [Backend & Auth](https://docs.5stack.gg/plugins/backend)
+- [Deploying](https://docs.5stack.gg/plugins/deploying)
+
+For a fuller example with a backend and a database, see the
+[inventory plugin](https://github.com/lukepolo/5stack-inventory-plugin).

index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>5stack Hello World (dev)</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

nginx.conf

@@ -0,0 +1,28 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+
+  # The panel imports remoteEntry.js cross-origin; allow any origin (public JS,
+  # no credentials). Handled here in the container — not in the ingress.
+  location / {
+    add_header Access-Control-Allow-Origin "*" always;
+    try_files $uri $uri/ =404;
+  }
+
+  # remoteEntry.js keeps a STABLE filename but its content changes every build,
+  # so it must never be cached by a CDN (Cloudflare) — otherwise a stale copy
+  # (or a cached 404) is served. Hashed /assets/* chunks stay cacheable.
+  location = /assets/remoteEntry.js {
+    add_header Access-Control-Allow-Origin "*" always;
+    add_header Cache-Control "no-store, no-cache, must-revalidate" always;
+    try_files $uri =404;
+  }
+
+  # Same reasoning: the panel re-reads the manifest to detect the plugin.
+  location = /5stack-plugin.json {
+    add_header Access-Control-Allow-Origin "*" always;
+    add_header Cache-Control "no-store, no-cache, must-revalidate" always;
+    try_files $uri =404;
+  }
+}