homeio

Public

Forked from doctor-io/homeio

Branch: main
Latest commit: 958d74616 October 2026

Contributing

This file is the canonical contributor guide. The root CONTRIBUTING.md points here to avoid divergent instructions.

Local Development Setup

Requirements:

Node.js 22.x
npm
PostgreSQL
Docker for Docker/App Store integration testing
Linux with NetworkManager/D-Bus only if working on network or USB host features

npm install
cp .env.example .env.local
createdb home_server
npm run db:init
npm run dev

Open http://localhost:3000. The app routes to /register if no users exist.

For Docker-based local setup, docker-compose.yml runs Homeio plus PostgreSQL and mounts the Docker socket.

Environment

Add server env vars to lib/server/env.ts and .env.example. Feature code should use serverEnv, not direct process.env.

Important env vars include:

DATABASE_URL
PG_MAX_CONNECTIONS
AUTH_SESSION_SECRET
AUTH_SESSION_HOURS
AUTH_ALLOW_REGISTRATION
LOG_LEVEL
LOG_TO_FILE
STORE_STACKS_ROOT
STORE_APP_DATA_ROOT
STORE_MAX_CONCURRENT_OPERATIONS
FILES_ROOT
DOCKER_SOCKET_PATH
DBUS_HELPER_SOCKET_PATH
TERMINAL_WS_REQUIRE_AUTH
HOMEIO_TELEMETRY
HOMEIO_TELEMETRY_URL
DEMO_MODE

D-Bus Helper

Network and USB host features depend on services/dbus-helper/. It is plain ESM JavaScript and talks to NetworkManager/udisks2 over D-Bus. Do not change it as part of a main-app-only task without running its tests and verifying the sidecar separately.

Workflow

Branches:

main: stable
feature/<name>: new features
fix/<name>: bug fixes

Commits use conventional prefixes:

feat: add Google Drive integration
fix: prevent EventSource reconnect loop after log.end
refactor: extract surface tokens to lib/ui/surface-tokens
docs: update roadmap for v1.5

Before opening a PR:

npm run lint
npm run build
npm run test

If touching the schema:

npm run db:generate
npm run db:migrate

Use npm run db:init for local initialization with care; it drops Drizzle migration history before rerunning migrations.

Add A Feature Module

Read conventions.md. In short:

Put client UI in modules/<feature>/.
Put server code in lib/server/modules/<feature>/.
Put shared contracts in lib/shared/contracts/.
Put query keys in lib/shared/query-keys.ts.
Add API routes under app/api/v1/<feature>/.
Add tests beside changed code.
Document the module under doc/modules/.

Design System

Homeio uses shadcn/ui on Radix primitives plus Homeio surface tokens. Prefer tokens in lib/ui/surface-tokens.ts:

Token	Use
`PANEL_SHELL`	Outer panel or window content shell
`PANEL_INSET`	Inner section
`BADGE_SURFACE`	Badge/chip
`MENU_SHELL`	Popovers and menus

Use cn() from @/lib/utils.

PR Checklist

Code follows conventions.md.
Protected /api/v1/** routes call requireApiSession().
New APIs have contracts in lib/shared/contracts/.
New query keys are in lib/shared/query-keys.ts.
Server files under lib/server/ import "server-only".
Tests cover service logic, route validation, and critical UI behavior.
npm run lint, npm run test, and relevant build/db commands were run.
Docs were updated when public routes, modules, env vars, or schemas changed.