Develop locally

Use local development when you are changing backend, frontend, tests, or docs.

Install dependencies

Python dependencies are managed with uv. Web dependencies use npm.

Run backend commands from the repository root:

uv run --extra dev pytest
uv run --extra dev ruff check src tests

Install web dependencies:

cd web
npm install

Run the backend and web UI

Start the API:

INVOICER_DB_PATH=.data/invoicer.sqlite3 uv run uvicorn invoicer.api.server:app --reload --host 127.0.0.1 --port 8000

Start the web UI in another terminal:

cd web
npm run dev

Open http://127.0.0.1:5173. The Vite dev server proxies /api to the local FastAPI backend.

Seed local data

Create a small deterministic fixture:

uv run invoicer app seed-demo --db .data/invoicer.sqlite3

Create a dense UX test ledger:

uv run invoicer app seed-rich --db .data/invoicer.sqlite3 --replace

--replace clears local finance records, history, and recovery rows while preserving app settings and managed backup files.

Run the standard verification loop

Run:

uv run --extra dev pytest
uv run --extra dev ruff check src tests
cd web && npm run build
cd web && npm run test:e2e
docker compose up -d --build
curl -fsS http://127.0.0.1:8000/api/health

Work on the docs

Install docs dependencies:

cd docs
npm install

Run the docs locally:

npm run dev

Build the static docs site:

npm run build

The build output goes to docs/.vitepress/dist.