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

1. Confirm the branch and inspect the nearest package.json, existing sibling modules, and package exports.
2. Search @homarr/common before creating a general-purpose helper. Read references/common.md for every public entrypoint and export.
3. Read references/architecture.md when the task crosses packages, runtimes, routing, data, widgets, integrations, cron jobs, Custom Widgets, or Workshop.
4. Keep the change in the deepest package that owns the behavior. Reuse public entrypoints rather than deep-importing implementation files.
5. Re-run targeted searches before documenting counts, consumers, or dependency edges; these change faster than the architectural seams.

Current toolchain

• Use Node 24.22.1 for application runtimes and Bun 1.4.2 for package management, pinned in mise.toml and package.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 dev starts only @homarr/nextjs. Start a standalone runtime explicitly when the task needs it.