@plumix/admin

Pre-built React SPA published as its own package and depended on by plumix. The admin compiles once into dist/, and the plumix Vite plugin resolves this package from node_modules and stages it into the consumer's .plumix/public/_plumix/admin/ directory so the active runtime adapter serves it at /_plumix/admin/* with no per-consumer rebuild.

Dev workflows

Two supported loops, pick whichever matches what you're iterating on.

Consumer-style: plumix dev only (single origin)

Once the consumer has wired static-asset serving for their chosen runtime (the example app's config shows the right binding for that runtime), running the backend serves admin too — no second process:

cd examples/minimal
pnpm dev                              # :5173
# open http://localhost:5173/_plumix/admin/

This mode exercises the same serving path production uses (the runtime's asset layer in front of the request handler). Best for "does my feature work end-to-end?" checks.

Admin-authoring: pnpm dev in both workspaces (two ports, HMR)

When iterating on admin source, Vite's HMR against admin source files is faster than rebuilding + restaging. Two terminals:

# terminal 1 — backend
cd examples/minimal && pnpm dev       # :5173

# terminal 2 — admin with HMR
cd packages/admin && pnpm dev         # :5174
# open http://localhost:5174/_plumix/admin/

Admin's Vite dev server proxies /_plumix/rpc and /_plumix/auth to :5173, so RPC and auth still hit the real backend. Best for "I'm tweaking a component, want hot reload."

Override the proxy target for a remote/non-default backend:

PLUMIX_BACKEND_URL=http://192.168.1.10:5173 pnpm dev

Turbo shortcut: pnpm dev from repo root

Runs both workspaces in parallel via turbo watch dev --continue. Same two-port layout as the two-terminal variant but in one shell.

First-time setup

Before RPC endpoints work, the dev database needs migrations applied — the specifics depend on the database adapter the example app uses. From your example app (e.g. examples/minimal):

cd examples/minimal
pnpm plumix migrate apply

End-to-end tests (Playwright + axe-core)

pnpm test:e2e launches a dedicated Vite server on :5180 and runs the Playwright suite against it. First-time setup needs Chromium installed:

pnpm exec playwright install --with-deps chromium    # once
pnpm test:e2e                                         # each run

The default suite is an accessibility baseline — axe-core with WCAG 2.1 AA tags run against the landing page. Every new route or feature should add a spec under e2e/.

Workspace-local scripts

From packages/admin/:

pnpm dev          # Vite dev server on http://localhost:5174/_plumix/admin/
pnpm build        # emits static assets to dist/
pnpm test         # vitest (jsdom + React Testing Library)
pnpm test:e2e     # playwright + axe-core (needs chromium installed once)
pnpm typecheck
pnpm lint

Stack

• React 19 + TypeScript
• TanStack Router (file-based, with @tanstack/router-plugin in Vite)
• TanStack Query + @orpc/tanstack-query for RPC against the plumix backend
• Tailwind CSS v4 (@tailwindcss/vite) + shadcn/ui (new-york style, neutral base)
• Geist Variable + Geist Mono Variable via @fontsource-variable/*
• Vitest + React Testing Library for component tests
• Playwright + @axe-core/playwright for e2e and accessibility baseline

Directory layout

src/
  App.tsx              root component
  main.tsx             Vite entry
  routeTree.gen.ts     generated by @tanstack/router-plugin
  types.d.ts           ambient declarations (fontsource, etc.)

  lib/                 non-React utilities
    constants.ts       ADMIN_BASE_PATH and similar
    orpc.ts            typed oRPC client singleton
    utils.ts           cn() helper for shadcn components

  providers/           React provider wiring
    query-client.ts    createQueryClient factory
    router.ts          createRouter factory
    theme.tsx          ThemeProvider (light/dark/system)
    index.ts           barrel re-export for App.tsx

  components/
    ui/                shadcn-vendored primitives (do not hand-edit — re-add
                       via `pnpm dlx shadcn@latest add <name>` to refresh)

  routes/              file-based routes (see @tanstack/react-router docs)

Adding a shadcn component

pnpm dlx shadcn@latest add <name>

Components land in src/components/ui/. Knip is configured to treat that directory as a vendored component library — unused primitives don't surface as noise, so add the full set you expect to use.

How the admin is shipped

Admin build output (dist/) is published as the @plumix/admin package, which plumix declares as a dependency. At consumer build time, the plumix Vite plugin resolves @plumix/admin from node_modules and copies its dist/ into the consumer's dist/_plumix/admin/, and the active runtime adapter serves them (see packages/core/src/runtime/dispatcher.ts for the runtime-agnostic request pipeline). Plugin-contributed admin chunks + the manifest that wires them are planned for a later phase — see docs/reference/architecture/09-packages/05-admin.md for the full design.