Full-stack skeleton
Monorepo workspaces for backend, frontend, and shared contracts. Bun drives installs, scripts, builds, and local services.
Spernakit v3
Spernakit
A self-hosted admin application template with the hard parts already wired.
Start from Bun, Elysia, Drizzle, React 19, shadcn/ui, TanStack Query, Zustand, and a template contract that expects real verification. Auth, RBAC, workspaces, audit logs, notifications, dashboards, uploads, health checks, settings, Docker deployment, and OpenAPI contract checks are part of the baseline.
- Runtime
- Bun + Elysia
- Frontend
- React 19 + Vite
- Data
- Drizzle + SQLite/PG
- Gate
- smoke:qc
The template
Build the product layer. Keep the foundation boring.
Spernakit is for side projects, internal tools, homelab apps, and small SaaS-style admin surfaces where the baseline should already include security, configuration, observability, and deployment structure.
Admin-grade security
JWT cookies, CSRF, account lockout, password reset policy, TOTP MFA, OAuth account linking, API keys, and a 5-tier RBAC hierarchy.
Operational features
Workspaces, audit logs, real-time notifications, scheduled tasks, health alerts, backups, uploads, dashboards, and settings.
Verification built in
The template expects drift checks, config checks, typecheck, lint, build, OpenAPI parity, route/page reachability, format, and deps.
Included systems
The features every admin app ends up needing.
The template is intentionally broad. Derived apps can turn features off or extend them, but they start from a working application surface instead of a pile of future TODOs.
Users, roles, sessions
User CRUD, soft delete, workspace membership, SYSOP bypass, password-change enforcement, token revocation, and role-aware UI.
Drizzle schema discipline
SQLite by default, PostgreSQL support, generated migrations, auto-migrate for SQLite, schema parity checks, and safe DB admin tools.
Ready admin shell
shadcn/ui, theme modes, responsive shell variants, command palette, global shortcuts, route splitting, skeletons, and error boundaries.
Health and background work
Health checks, health alerts, system metrics, scheduled task history, pino logs, backups, restore flows, and Docker deployment.
One type contract
Shared pure types live in shared/. The
OpenAPI spec at
/api/v1/docs/json anchors frontend API
parity.
Built for derived apps
Template drift checks and a fleet manifest help derived apps consume template improvements without losing app-specific behavior.
Quality gate
Every change runs the same checks.
Spernakit treats quality gates as part of the template surface. A change that adds a route must register it, pages have to be reachable, and config and schema artifacts must stay aligned. Dependency versions are exact.
The main gate is bun run smoke:qc. UI
work also gets crawl-tested against affected routes.
| Layer | Guard | What it catches |
|---|---|---|
| Template | check:drift | Unexpected divergence from the template-managed baseline. |
| Config | check:config, config:validate, schema drift | Invalid JSON config, stale schemas, and unsupported env spread. |
| Code | typecheck, lint, build, max-lines | Type errors, lint warnings, oversized files, and broken builds. |
| API | check:api-types | Frontend type drift from backend TypeBox/OpenAPI contracts. |
| Reachability | check:feature-integration | Route plugins and pages that exist but are not wired. |
| Database | check:db-location, schema parity | Wrong database placement and SQLite/PostgreSQL schema mismatch. |
Trust model
Security ships in the baseline.
Spernakit ships security-sensitive flows as working template code, documents the boundaries, and keeps derived-app exceptions explicit.
Protected by default
Route guards, component-level authorization, CSRF, CSP, rate limiting, token blacklist, password policy, and MFA live in the baseline.
Workspace isolation
Non-SYSOP users act only inside member workspaces. SYSOP cross-workspace access is deliberate and represented in shared role utilities.
JSON-only surface
Static config is JSON and schema-validated.
bunfig.toml sets
env = false; secret injection is
narrowly documented.
Public policy docs
Review the security policy, license, and template docs before shipping a derived app.
Start
Get it running locally.
Spernakit expects Bun 1.3.14+ and Node 24.x compatibility tooling. SQLite is
the default database, with PostgreSQL supported through
config.database.dialect.
Local setup
git clone https://github.com/NomadicDaddy/spernakit.git
cd spernakit
# Install dependencies and initialize config/database state
bun run setup
# Or for an existing checkout
bun install
bun run db:setup
# Start both services with log aggregation
bun run dev
# Prove the template before committing
bun run smoke:qc