Thomas Camlong
f1fb760c69
Batch-update dependencies from 17 open renovate PRs: - @modelcontextprotocol/sdk 1.26→1.29, tiptap 3.25→3.26, ioredis 5.11.0→5.11.1 - mysql2 3.22.4→3.22.5, sql.js ^1.12→^1.14, @types/react 19.2.16→19.2.17 - oxlint ^1.67→^1.68, oxfmt ^0.53→^0.54, concurrently ^9→^10, mantine-contextmenu ^7→^9 - postcss ^8.4→^8.5.10 (security), @fec/remark-a11y-emoji ^3→^4 Migrate docs Tailwind CSS v3 → v4: - Replace tailwindcss v3 + autoprefixer with tailwindcss v4 + @tailwindcss/postcss - Convert config from tailwind.config.js to CSS @theme block - Update PostCSS plugin in docusaurus.config.ts Upgrade GitHub Actions: - configure-pages v5→v6, upload-pages-artifact v4→v5, deploy-pages v4→v5 - EndBug/add-and-commit v9→v10, git-auto-commit-action v5→v7 Migrate pnpm v10 → v11 (unblocks #5679): - Move package.json#pnpm config to pnpm-workspace.yaml - Convert onlyBuiltDependencies/ignoredBuiltDependencies to allowBuilds map - Migrate .npmrc settings (nodeLinker, strictPeerDependencies, engineStrict) - Update packageManager to pnpm@11.5.2 Fix proxmox-api undici type incompatibility: - Cast fetch parameter to resolve type mismatch between bundled undici versions Fix integration cache not invalidating after create/update/delete: - Add utils.integration.all.invalidate() to all mutation onSuccess handlers - Previously only Next.js server cache was revalidated, not client tRPC cache
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/ # 55 integration guides (one folder each)
├── widgets/ # 42 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.