Core Internals
Contributor-focused engine notes — build, discovery, Bun runtime.
Core Internals
This section is for framework contributors and engineers who want a precise mental model of how Manic turns app/ conventions into a Bun-hosted SPA (and optional Hono API). Every article maps to packages/manic/src.
Stack overview
Speed & perceived performance
Understanding speed
On-ramp — why Manic feels fast + reading order
Performance model
Architecture vs typical stacks tradeoffs
Production client bundle
Hashed Bun.build HTML Tailwind NODE_ENV
HMR & Fast Refresh
Dev oxc refresh Router cache clear
Lazy chunks & cache
componentCache prefetch bandwidth memory
Fullstack API runtime
/api OpenAPI prod vs dev loader roots
Topics
Source layout
packages/manic/src directory map
Architecture
Client router, server, plugins — system diagram
Build pipeline
Ordered manic build stages tied to build.ts
Bundler & transform
oxcPlugin matrices per Bun.build target
Discovery engine
Glob scoring manifest generation watchRoutes
OXC toolchain
Transform minify lint fmt resolver roles
Dev internals
manic dev bunfig spawn config reload
Router runtime
matcher globals navigate prefetch VT
Plugin hooks
preload configureServer build ordering
Providers contract
ManicProvider.build BuildContext
Server runtime
createManicServer modes HTML negotiation plugins
Caveats
CLI quirks caching globs provider ordering
Manic internals advanced
Config manifest companion narrative
Plugin architecture
createPlugin providers user-facing guide
Architectural principles
| Principle | What it means in practice |
|---|---|
| Bun-native I/O | Bun.serve, Bun.build, Bun.Glob, Bun.spawn, Bun.file — no dual Node compatibility shim layer inside the framework core |
| OXC vertical slice | oxc-transform, oxc-minify, oxlint, oxfmt share toolchain assumptions (OXC) |
| Filesystem conventions | Routes + APIs discovered by scanning app/, not manual registration lists (Discovery) |
| Explicit tradeoffs | Type stripping without tsc, lint parity quirks, plugin apiRoutes: [] during build() — documented under Caveats |
Repository layout
| Path | Responsibility |
|---|---|
packages/manic/src/cli | manic commands · build.ts orchestrates production graphs |
packages/manic/src/server | createManicServer · discovery.ts manifest helpers |
packages/manic/src/router | Client SPA router Link navigate matcher scoring |
packages/manic/src/config | defineConfig loadConfig createPlugin |
packages/manic/src/plugins | apiLoaderPlugin fileImporterPlugin |
packages/providers | Deployment adapters consumed after provider.build |
Where to start reading
| Goal | Page |
|---|---|
| Understand speed end-to-end | Understanding speed · Performance model · Benchmarks |
Understand manic build ordering | Build pipeline |
Understand createManicServer branches | Server runtime |
| Ship reliable plugins | Framework plugins + Caveats |