Thomas Camlong
89f081538c
The branch was 12 commits behind dev and GitHub reported it CONFLICTING, which is
why the real CI workflow had not run since 2026-08-10 - a conflicting PR has no
mergeable ref, so pull_request-triggered workflows are skipped. Only the
lightweight checks (semantic title, CodeQL, CodeRabbit) were still reporting,
which made the PR look green while nothing was actually being tested.
Three conflicts, all of them this branch's barrel-diet work meeting dev's new
What's Up Docker integration. In every case the branch's structure is kept and
WUD is absorbed into it rather than the reverse:
integrations/base/creator.ts keep the lazy loader map; add wud as
() => import(...) rather than dev's static import,
which would have undone the lazy creator
integrations/src/index.ts keep the slim barrel; re-export WudStats and
WudContainerUpdate as `export type`, which is
erased at build and so adds no runtime module
widgets/src/index.tsx stays deleted - this was the barrel that put
every widget in the initial client graph
Registering WUD in the slimmed structures then needed three more entries that the
merge could not infer: base/kind-map.ts (type-only kind -> class map),
widgets/src/import.ts (type-only WidgetImports map, both the import and the
member). Each was found by typecheck rather than guessed at.
Verified: 37/37 packages typecheck, 1866/1881 unit tests pass. The 3 failures are
home-assistant and pi-hole, both testcontainers-based; both pass 11/11 in
isolation and fail only under 150-file parallel load with the container's payload
half-initialised.
Homarr Documentation (@homarr/docs)
The official homarr.dev documentation site, built with Docusaurus 3 and living inside the Homarr monorepo.
Why it's in the monorepo
Having documentation alongside the application code enables:
- Two-way linking — the docs app imports from
@homarr/definitionsfor type-safe integration/widget metadata, and the main app references doc paths via generated sitemap types - Atomic PRs — code changes and their documentation updates ship in the same pull request
- Shared tooling — same Node version, pnpm catalog, oxlint/oxfmt, CI pipeline
- Build-time validation — Docusaurus strict mode catches broken links and references at build time
Development
From the monorepo root:
# Start the docs dev server (port 3003)
pnpm dev:docs
# Or from within this directory
pnpm dev
Build
# Build docs only
pnpm turbo build --filter=@homarr/docs
# Build everything (docs + main app + tasks + websocket)
pnpm build
Lint & Format
Uses oxlint and oxfmt (same as the rest of the monorepo):
pnpm lint # oxlint
pnpm format # oxfmt (check)
pnpm format -- --write # oxfmt (fix)
Typecheck
pnpm typecheck
Content Structure
docs/
├── getting-started/ # Installation guides, glossary, prerequisites
├── management/ # Boards, apps, users, integrations, settings, tasks, API
├── integrations/ # 56 integration guides (one folder each)
├── widgets/ # 43 widget guides (one folder each)
├── advanced/ # SSO, env vars, proxy, styling, CLI, development
└── community/ # FAQ, donate, license, translations, get-in-touch
Each integration/widget doc follows a consistent pattern:
index.ts— typed metadata (IntegrationDefinition/WidgetDefinition)index.mdx— content using shared React components (IntegrationHeader,WidgetHeader, etc.)
Importing from homarr packages
The docs app has @homarr/definitions as a workspace dependency. You can import integration kinds, widget kinds, and other definitions directly:
import { IntegrationKind } from '@homarr/definitions';
This enables type-safe references to homarr domain concepts within documentation code.
Search (Algolia DocSearch)
Search uses the Docusaurus Algolia index (crawler cd77a285-2756-4557-bf21-ee703748df15). A separate markdown index is built for LLM markdown indexing.
Crawler reference config: docsearch.config.js.
Verify search health:
pnpm verify:search
Tech Stack
| Layer | Technology |
|---|---|
| Site generator | Docusaurus 3 (@docusaurus/preset-classic) |
| Styling | Tailwind CSS 3 + Docusaurus Infima |
| Icons | @tabler/icons-react |
| Diagrams | Mermaid (@docusaurus/theme-mermaid) |
| Search | Algolia DocSearch |
| Analytics | PostHog |
| Charts | @nivo/line |
Contributing
When making changes to the homarr codebase that affect user-facing behavior, always update the corresponding documentation in this app. See .cursor/rules/documentation-sync.mdc for the complete mapping of code changes to doc locations.