ServerKit/docs/CORE_SLIM.md

Core-slim: which core pages become extension-delivered

Decision doc — plan 25 Phase 6 (#18 / Extensions Platform #39). No code moves in this document. It classifies the surfaces, fixes the order, and gives a per-page migration checklist. Each move is its own small follow-up slice, tracked against this doc.

Why now

Plan 25 landed the last missing rail: an extension can ship a prebuilt runtime frontend bundle that the panel loads without a rebuild, integrity-verified. Combined with the already-proven install / update / survival / config / socket / jobs rails, a vertical no longer has to live in core to have a real UI. So the question is no longer "can a page be an extension" but "which ones should move, in what order, and how far".

Two speeds already exist (decision D2): a thin-wrapper builtin owns the route/nav/palette via its manifest while its page component + backend stay in core (e.g. serverkit-gpu's frontend/index.jsx is just import GpuMonitor from '../../pages/GpuMonitor'). Core-slim is about finishing the extraction: moving the UI into the extension dir so the extension is self-contained — and, where it makes sense, shipping it as a runtime bundle so it can leave the repo entirely.

Tiers

Tier A — already self-contained (done)

Frontends already live in the extension dir; nothing to move.

Extension	Notes
serverkit-crowdsec	Reference implementation of the sanctioned page skeleton.
serverkit-dns-server	Self-contained.
serverkit-mail	Self-contained (Stalwart mail engine).
serverkit-gui	Self-contained; first runtime-bundle migration (plan 25 Phase 4).

These are the template to copy. serverkit-gui specifically proves the runtime-bundle path (externalized build, CSS inlined) — Tier B/C follow it.

Tier B — thin wrappers whose UI still lives in core/pages

Each has an extracted backend + a manifest that owns its route, but its page component (and helpers/styles) still lives under frontend/src/pages/. Ordered smallest / least-coupled first so the early moves establish the pattern cheaply. Sizes are the core page's current line count (the UI to relocate).

#	Extension	Core page	~lines	Coupling notes
1	✅ serverkit-gpu	GpuMonitor.jsx	199	DONE (plan 32 #7, 2026-07-06). Backend moved to builtin-extensions/serverkit-gpu/backend (entry_point gpu:gpu_bp, url_prefix /api/v1/gpu); page moved to frontend/components/GpuMonitor.jsx (SDK imports); core page + core app/api/gpu.py + app/services/gpu_service.py deleted; sdk_version ^1.0.0 declared. Shipped baked (dual-path per guardrail below); runtime-ESM build scaffold added, live runtime-loader render deferred with plan 32 #9.
2	serverkit-cloud-provision	CloudProvision.jsx	239	One page; leans on connection APIs already in core.
3	✅ serverkit-cloudflare-ops	CloudflareZoneSettings.jsx	469	DONE (plan 52 Ph2 prep, 2026-08-29). Page + WAF/Workers/Tunnels/Storage panels + own API client + SCSS moved into builtin-extensions/serverkit-cloudflare-ops/frontend/; DNS records + CF connection stay core. Standalone repo prepared (operator publishes).
4	serverkit-remote-access	RemoteAccess.jsx	516	WireGuard pairing UI; agent-fleet coupling via SDK.
5	serverkit-ftp	FTPServer.jsx	687	Accounts CRUD; self-contained once helpers move with it.
6	serverkit-status	StatusPages.jsx	747	Has a public status route (/status/:slug) that must stay reachable — verify the public path still resolves post-move.
7	✅ serverkit-email	Email.jsx	1086	DONE (plan 52 Ph2 prep, 2026-08-29). Page + own API client + SCSS moved into builtin-extensions/serverkit-email/frontend/; DNS-provider + relay methods stay core (Settings surfaces). Standalone repo prepared (operator publishes).
8	serverkit-workflows	WorkflowBuilder.jsx	1092	Largest Tier B; pulls in @xyflow/react — externalize it or bundle it into the extension (it is NOT a host-shared lib).
9	serverkit-git	Git page group	—	Already plugin-contributed self-rendering (sk-tabgroup shell). Mostly a file-move; last in Tier B because its tab-group wiring is the closest analog to Tier C.

Shared-lib caution (Decision 2): only react, react-dom, react/jsx-runtime, react-router-dom, serverkit-sdk are externalized by the host import map. Anything else a page uses today from core (charts via recharts, flow via @xyflow/react, icons via lucide-react) must either be bundled into the extension or first promoted into the SDK. Workflows (@xyflow/react) and any chart-heavy page are the ones this bites.

Tier C — WordPress ✅ DONE (plan 52 Phases 4-5, 2026-08-05)

serverkit-wordpress is fully extracted: Phase 4 moved the frontend (5 pages, 40 components, 3 SCSS files) into the extension and onto the serverkit-sdk surface; Phase 5 took it out of the tree into the standalone serverkit-wordpress repo as a runtime-ESM bundle (SDK 1.2.0). It distributes through the registry and is offered during onboarding from the bundled index entry; its schema stays core via the documented core data seam (D1).

Per-page migration checklist

For each Tier B/C page, one slice:

1. Move the UI from frontend/src/pages/<Page>.jsx (+ its private components/styles) into builtin-extensions/<slug>/frontend/. Replace the thin import … from '../../pages/<Page>' re-export with the real component.
2. Rewrite imports to the SDK: swap deep @/components/ds, contexts, and api for serverkit-sdk imports (the lint flags deep @/ for external extensions). Keep the same /api/v1/<feature> prefix (decision D9).
3. Handle non-shared deps: bundle them into the extension, or promote a genuinely common one into the SDK (a deliberate SDK minor bump).
4. Delete the core copy: remove the page import + <Route> + PAGE_TITLES entry from App.jsx, the sidebarItems.js/group-tabs entry, and the CommandPalette.jsx entry. The manifest already owns these.
5. Pre-bundle: node scripts/sync-builtin-frontends.mjs (baked path) — the CI drift gate (--check) keeps source/artifact in sync.
6. (Optional) runtime bundle: to ship it as an external (non-baked) extension, add the --template frontend-esm build (vite.config.mjs externalizing the shared libs → dist/index.mjs), set frontend_entry: dist/index.mjs + sdk_version, and validate with new-extension.mjs --validate. See EXTENSIONS_CI.md.
7. Verify: npm run lint && npm run build; the screenshots skill renders the page; for serverkit-status confirm the public /status/:slug route still resolves; backend suite green.
8. Keep it brand-neutral and free/OSS (project policy).

Migration log

slice 1 — serverkit-gpu (2026-07-06, plan 32 #7)

Checklist status:

1. Move the UI ✅ — builtin-extensions/serverkit-gpu/frontend/components/GpuMonitor.jsx (index.jsx renders it instead of re-exporting the core page).
2. Rewrite imports to the SDK ✅ — PageTopbar, KpiBand, api, useToast from serverkit-sdk; EmptyState + Button via the @/ alias (not yet on the SDK surface — tolerated for the baked path; a runtime-ESM build must bundle them or the SDK must promote them, a deliberate minor bump).
3. Handle non-shared deps ✅ — only lucide-react (bundled on the baked path). GPU styles (_gpu.scss) stay in core design-system SCSS for the baked slice; a runtime-ESM build would inline them into the bundle (as gui does).
4. Delete the core copy ✅ — core page, app/api/gpu.py, app/services/gpu_service.py, and the core gpu_bp registration removed. The manifest already owned nav/route/palette/title.
5. Pre-bundle ✅ — node scripts/sync-builtin-frontends.mjs; CI --check drift gate green.
6. (Optional) runtime bundle 🚧 — frontend/vite.config.mjs + package.json scaffold added (externalizes the shared libs → dist/index.mjs), sdk_version declared. Kept baked for this release (dual-path guardrail); flipping frontend_entry to dist/index.mjs + cutting a registry release is deferred to plan 32 #9 (needs push/publish + a test box).
7. Verify ✅ — npm run lint && npm run build clean; backend suite green (test_gpu_extension.py bridge tests + pipeline runtime-builtin SDK-gate fixture). No public route to re-check (gpu has none).
8. Brand-neutral + free/OSS ✅.

Non-goals / guardrails

• No big-bang. One page per slice; the app stays shippable between slices.
• Backend stays put unless a slice explicitly extracts it — most Tier B backends are already extracted; the UI is the remaining half.
• SDK is the throttle. Every "promote a dep into the SDK" is a versioned contract change (SDK_VERSION bump) — do it deliberately, not per-page.
• Dual-path during any runtime move: keep the baked frontend for one release before deleting it, so panels mid-upgrade never lose the page.

Sequence summary

Tier A (done) → Tier B in the numbered order above (gpu → cloud-provision → cloudflare-ops → remote-access → ftp → status → email → workflows → git) → Tier C (wordpress). Reassess after serverkit-git whether WordPress moves as one slice or several sub-tab slices.