* feat: migrate tooling and runtimes to bun * fix: serialize act installs and adapt backup checks * fix: finish bun scripts and rootless act setup * fix: support bun images in runtime benchmarks * fix: keep a single bun toolchain configuration * fix: include docs mascot sources in workshop build * docs: use bun in remaining tool commands * fix: complete bun sqlite development tooling * docs: explain sqlite development adapter * fix: align remaining commands and local ci validation * fix: use renovate regex fallback with bun * fix: finalize bun sqlite connections during cleanup * fix: preserve sqlite foreign key enforcement * fix: align docker build frontends * fix: prepare release versions with bun * Add Bun benchmarks and preserve SQLite connection defaults * Benchmark Bun installs, conflicts and production workloads * Force Bun workspace tools and HTTP/1.1 upstream streaming * Exclude benchmark evidence from Docker contexts * Expose branch benchmarks through CI * Verify hydrated widget data in production benchmarks * Measure image archives and document benchmark protocol * Audit dependency sharing across every workspace * Pin pnpm for nested baseline benchmark scripts * Preserve nested manager pinning on benchmark resume * Include application and runtime image footprints * Fail benchmark gates on candidate command errors * Report complete build overhead and sampled memory bounds * Validate migration comparisons across pinned revisions * Record configurable runtime memory budgets * Retain out-of-memory kills in runtime budget probes * Reject OOM events consistently across runtime metrics * Record complete Bun migration benchmarks * Record memory diagnosis and correct Turbo caching * Use Bun package management while preserving Node runtimes * Keep native build fallbacks and exclude development artifacts * Fix Node ESM metadata and isolate local CI configuration * Measure development performance and isolate act environment * Support isolated environment files in rootless act * Validate the full migration range with act * Preserve native SQLite binding for bundled migrations * Use documented dev defaults and report benchmark scope * Validate dev defaults and isolate restart measurements * Record package-manager and development benchmarks * Keep benchmark measurements and link full command artifacts * Clean up temporary act environment files * Validate Node runtimes in package-manager comparisons * Validate every workspace in manual CI runs * Retain patched nested brace expansion versions * Complete package-manager and Node performance report * Normalize archived benchmark logs * Record final hosted validation * Cache both Next builds with platform isolation * Prime cache with write-only mode * Split Next artifacts below Cloudflare upload limit * Assemble coherent standalone cache outputs * Preserve traced middleware entrypoints * Assemble traced directory links before files * Separate cached dependencies from assembled output * Record signed Turbo cache benchmarks * Remove archived benchmark captures Full benchmark evidence is preserved at 8f7d3bcd14109bfb13fa664d31710b88d820ad66. * Remove migration benchmark harness * fix: correct migration launch and local Act prerequisites * Consolidate Turbo caches and production artifacts * Exclude generated files from Docker cache inputs * fix: address Bun migration review findings * fix: check restored compiler bundle manifests
7.0 KiB
Homarr architecture
Contents
Applications and runtimes
| Path | Role |
|---|---|
apps/nextjs |
Main Next.js application and HTTP APIs on port 3000 |
apps/docs |
Next.js and Fumadocs documentation site on port 3003 |
apps/tasks |
Cron-job initialization and scheduling runtime; it does not expose the old port-3002 API |
apps/websocket |
tRPC WebSocket subscriptions on port 3001 |
apps/workshop |
Go/PocketBase Workshop service and provider integration |
bun run dev runs only @homarr/nextjs. Use bun run --filter @homarr/tasks dev, bun run --filter @homarr/websocket dev, or bun run dev:docs when a task needs those runtimes.
In production, apps/nextjs/src/instrumentation-node.ts starts the tasks and WebSocket runtimes inside the Bun process. Nginx listens on port 7575, proxies /websockets to port 3001, and sends other traffic to port 3000. Redis can run internally or externally.
Package map
Foundation and domain
core: environment validation, database and Redis factories, logging, infrastructure.definitions: domain enums, integration definitions, widget kinds, permissions.common: shared utilities with environment-specific entrypoints. Search it before adding helpers.validation: shared Zod schemas.server-settings: typed server-setting keys and access.
Data, identity, and transport
db: Drizzle schemas, queries, migrations, and SQLite and PostgreSQL drivers.auth: Auth.js/NextAuth configuration, sessions, providers, and API keys.api: tRPC routers, contexts, MCP metadata extraction, OpenAPI, and client/server entrypoints.redis: Redis clients, pub/sub channels, and caches.cron-jobs-core,cron-jobs,cron-job-status: scheduling primitives, job implementations, and status transport.
Backends and external systems
integrations: typed clients for external applications.request-handler: shared server request flows.docker,ping,image-proxy,icons,analytics: bounded infrastructure capabilities.custom-widgets: Custom JSX v2 schema, validation, runtime, and security contracts.workshop: TypeScript Workshop client, backend contracts, and schemas used by Homarr.
UI and composed features
ui: shared Mantine components, theme, and hooks. Search here before creating a primitive.form,forms-collection: Zod-backed form setup and reusable forms.modals,modals-collection: modal primitives and feature modals.boards: board state, edit mode, and cache coordination.settings,spotlight,notifications,onboarding: cross-feature UI flows.widgets: widget definitions, dynamic component loaders, and shared widget UI.translation: next-intl configuration and locale catalogs.cli: Bun operations CLI.tools/homarr-devis the separate Go developer CLI.
Dependency direction
Prefer these directions; verify the exact dependency in package manifests before changing a boundary.
- Put infrastructure in
coreand stable domain names indefinitions. - Put reusable, dependency-light helpers in
common; use its public environment-specific entrypoints. - Build persistence in
db, identity inauth, transport inredis, and external clients inintegrations. - Compose server behavior in
api,cron-jobs, and request-handler packages. - Build primitives in
ui,form, andmodals; compose product surfaces in widgets and collection packages. - Keep app entrypoints in
apps/*thin. Avoid moving reusable behavior intoapps/nextjswhen a package already owns it.
Core patterns
tRPC and MCP
packages/api/src/root.ts lazily composes the application router. Server components use @homarr/api/server; client components use @homarr/api/client. MCP extraction requires the eager router in packages/api/src/mcp.ts, so MCP-enabled subrouters must be imported and registered there directly. Use the mcp-integration skill for exposure and security rules.
Databases
Drizzle schemas live in packages/db/schema/. DB_DRIVER selects better-sqlite3 or node-postgres; MySQL and MariaDB are no longer runtime drivers in v2. Existing MySQL installations must use the documented converter before upgrading. Migrations live under packages/db/migrations/sqlite/ and packages/db/migrations/postgresql/.
Widgets
packages/widgets/src/registry.ts owns the explicit widget-module and component-loader registries. packages/widgets/src/manifest.ts caches those loaders and exposes definitions, components, and combined resources. Widget modules use createWidgetDefinition and typed option builders. Data commonly comes from tRPC queries or Redis-backed cron results. Use existing shared widget components before creating local variants.
Integrations
packages/definitions/src/integration.ts owns integrationDefs and IntegrationKind. packages/integrations/src/base/creator.ts owns createIntegrationAsync; concrete integrations implement the shared base contract. Keep credentials and permission checks on server-owned paths.
Cron jobs
Jobs live in packages/cron-jobs/src/jobs/ and use createCronJob. apps/tasks initializes and starts the job group. Job results and status can flow through Redis and tRPC; the retired port-3002 management-API model is no longer part of the architecture.
Routing and localization
User routes live below apps/nextjs/src/app/[locale]/; the locale segment does not add a URL prefix. Route groups organize home and board surfaces. Administrative routes live under manage, Custom Widget configuration has a token route, and Workshop has a management surface.
Custom Widgets and Workshop
packages/custom-widgets owns the Custom JSX v2 contract. packages/workshop is the Homarr-side client/contract package; apps/workshop is the separate Go/PocketBase service. Use the homarr-custom-widget skill for authoring and security constraints.
Commands and conventions
- Read current scripts from the root or package
package.json; avoid caching commands that do not exist. - Use
bun run devfor Next.js,bun run dev:docsfor docs, andbun run dev:cli -- <args>for the Go developer CLI. - Use
bun run docker:dev:upfor the Redis development dependency. - Follow the Testing section in
AGENTS.mdfor test creation and validation scope. - Use
~/*only inside the Next.js app. Use public@homarr/*entrypoints across package boundaries. - Keep Mantine application styles separate from the Tailwind-based docs app.