ajnart
1b544f599c
Board scaling: no sideways scrolling - Revert the pannable narrow canvas. The canvas fits the viewport again and `.viewport` goes back to `overflow: clip`, so a board can never widen the document or scroll horizontally. - Fix the unreadable-narrow-board regression at the real cause instead: cap the inverse UI compensation at 2x (50% canvas scale). Down to 50% text and controls keep their physical size; below it the board zooms out as a whole, so a 200x200 logical tile hosts at most 28px logical text rather than 96px and content stops overlapping its neighbours. Touch editing - Add `touch-action: none` to `.board-grid-entry`, the dnd-kit draggable and its own drag handle. The 200ms touch activation delay is useless if the browser has already handed the gesture to page panning and emitted `pointercancel`. Only edit mode renders this element. Custom widgets - Memoize the merged `data`/`status`/`options` passed to `CustomJsxRenderer`. They were rebuilt every render, so the compiled-template memo never hit and the new reference-identity boundary key changed on every render, resetting the error boundary and forcing an extra reconciliation of the widget subtree. - Keep the cache key when the shared Redis cache is unavailable so the process-local cache still absorbs polling instead of sending every widget refresh upstream. - Reclaim the shared cache's LRU/size/byte bookkeeping for TTL-expired entries and touch the LRU in the same script, so expired ghosts stop consuming the 64 MiB budget and a read costs one round trip instead of two. Forwarded IP - Restore `ipAddressFromHeaders` to the full forwarding chain and add `trustedIpAddressFromHeaders` for the last hop. Repointing the shared helper had collapsed MCP failed-auth rate limiting into a single bucket for every client behind a reverse proxy and replaced the client IP with the proxy IP in API-key auth logs. Runtime and restore - Make the new /appdata ownership migration best-effort. Under `set -e` a mount that rejects chown (CIFS/SMB, fixed-uid NFS) turned into a container that refuses to start, and /appdata was never chowned before. - Report malformed metadata.json as such instead of blaming the archive.
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
# Point the docs at a local PocketBase instance
WORKSHOP_API_URL=http://127.0.0.1:8090 pnpm dev:docs
The standalone docs use WORKSHOP_API_URL for PocketBase and HOMARR_WEBSITE_URL for the public site origin. The old
WORKSHOP_URL name is a deprecated one-release alias.
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:fix # 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 4 + 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.