* 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
2.7 KiB
2.7 KiB
name, description
| name | description |
|---|---|
| codebase-context | Navigate Homarr's monorepo architecture and reuse shared packages. Use when locating code, choosing a package boundary, understanding runtime services, tRPC, databases, widgets, integrations, cron jobs, Custom Widgets, Workshop, or checking @homarr/common before creating a utility. |
Homarr Codebase Context
Orient from the current checkout before editing. Treat package manifests, exports, and source as authoritative when they differ from this snapshot.
Workflow
- Confirm the branch and inspect the nearest
package.json, existing sibling modules, and package exports. - Search
@homarr/commonbefore creating a general-purpose helper. Read references/common.md for every public entrypoint and export. - Read references/architecture.md when the task crosses packages, runtimes, routing, data, widgets, integrations, cron jobs, Custom Widgets, or Workshop.
- Keep the change in the deepest package that owns the behavior. Reuse public entrypoints rather than deep-importing implementation files.
- Re-run targeted searches before documenting counts, consumers, or dependency edges; these change faster than the architectural seams.
Current toolchain
- Use Node
24.18.0for application runtimes and Bun1.4.2for package management, pinned inmise.tomlandpackage.json. - Use Bun workspaces with Turborepo and a shared hoisted install. Workspace packages use the
@homarr/scope and catalog-managed dependencies. - Use Next.js App Router, TypeScript, tRPC, Drizzle, Mantine v9, Tabler icons, Jotai, TanStack Query, next-intl, Vitest, and Playwright.
- Use oxlint and oxfmt. Mantine is the application UI system; Tailwind is limited to the docs app.
bun run devstarts only@homarr/nextjs. Start a standalone runtime explicitly when the task needs it.
High-value seams
- Server/RSC tRPC:
@homarr/api/server - Client tRPC hooks:
@homarr/api/client - Main router:
packages/api/src/root.ts - MCP eager router:
packages/api/src/mcp.ts - Database schemas:
packages/db/schema/{sqlite,postgresql}.ts - Widget registry:
packages/widgets/src/registry.ts - Widget loading manifest:
packages/widgets/src/manifest.ts - Integration definitions:
packages/definitions/src/integration.ts - Integration factory:
packages/integrations/src/base/creator.ts - Cron jobs:
packages/cron-jobs/src/jobs/ - App routes:
apps/nextjs/src/app/[locale]/
Invoke documentation-sync only when users need new or corrected information to set up, use, or troubleshoot Homarr; follow the Documentation Sync criteria in AGENTS.md. When exposing tRPC through MCP, invoke mcp-integration.