Invoice Builder tackles a common but often painful problem for freelancers and small businesses: how to manage invoicing and quoting efficiently without relying on cloud services that lock you in or expose your data. It offers an offline-first desktop app built with Electron and TypeScript, featuring a dual-database backend that supports both local SQLite and server PostgreSQL deployments. This design lets you run it entirely on your desktop or self-host it via Docker for multi-user access.
What Invoice Builder does and how it is architected
At its core, Invoice Builder is an open-source invoicing and quoting application designed to prioritize data ownership and offline access. The core tech stack includes TypeScript for both frontend and backend logic, with Electron packaging the desktop client. The backend uses Node.js exposing a REST API.
The standout architectural feature is the dual-database support. Locally, the app uses SQLite, an embedded file-based database that fits perfectly with the offline desktop use case. When deployed on a server via Docker, it switches to PostgreSQL, enabling concurrent multi-user access and more robust server capabilities.
This duality is implemented behind an abstraction layer in the data access code, allowing the same codebase to transparently support both databases. This pattern is elegant because it avoids maintaining separate code paths or forks for desktop and server modes.
For deployment, the project offers two Docker Compose setups: one with separate backend and frontend containers, and another single container option. The frontend is a React-based SPA served via nginx in production mode, while the backend is a Node.js REST API listening on port 3000. The Docker setup handles reverse proxying with nginx to unify API calls under the frontend server, simplifying networking.
Invoice Builder also supports European e-invoicing standards, specifically UBL 2.1 and Peppol BIS 3.0 compliance, which is a significant plus for users needing to meet these regulatory requirements. It includes a customizable PDF generation engine and multi-currency support, making it flexible for international freelancers.
Technical strengths and architectural tradeoffs
The dual-database architecture is the repo’s most interesting technical aspect. By abstracting the data layer, the developers enable a single codebase to serve two very different operational modes: offline desktop and multi-user server. This reduces maintenance overhead and increases code reuse.
However, this approach is not without tradeoffs. Supporting both SQLite and PostgreSQL means the data access layer must handle differences in SQL dialects, concurrency, and transaction semantics gracefully. The code is surprisingly clean in this regard, which suggests careful design.
Electron as a desktop platform fits well for offline-first apps, delivering a consistent experience across OSes. But Electron apps tend to have a sizable memory footprint, and Invoice Builder recommends at least 2 GB RAM. This is a reasonable tradeoff considering the features and PDF generation complexity.
The PDF generation engine is customizable, allowing users to tailor invoice templates. This flexibility is useful but adds complexity. The app also supports full data import/export in JSON and XLSX formats, which is essential for migration or bulk operations.
The Docker deployment is practical, leveraging nginx as a reverse proxy to route backend API calls internally. The split container approach (backend and frontend separate) is recommended, improving modularity and scalability. The single container option exists for simpler setups but mixes concerns.
One limitation is the app’s memory and disk footprint: the installer is around 200 MB, and the app itself around 550 MB. This is not lightweight compared to purely web-based solutions, but it aligns with Electron’s typical overhead.
Overall, the repo balances practicality with technical complexity in a way that favors maintainability and user control.
Quick start with Docker
Invoice Builder provides clear Docker-based self-hosting instructions, suitable for users wanting centralized access or easy backups.
The default recommended setup uses two containers:
docker compose pull
docker compose up -d
This brings up:
| Container | Port | Role |
|---|---|---|
backend | 3000 | Node.js REST API + SQLite/PG |
frontend | 3001 | Static SPA served by serve |
Alternatively, a single container option runs both backend and frontend:
docker compose -f docker-compose.standalone.yml up -d
This runs on ports 3000 (API) and 3001 (SPA) but combines both services.
The Docker image is published on GitHub Container Registry and can be pulled by:
docker pull ghcr.io/piratuks/invoice-builder:latest
No additional environment variable configuration is needed for standard Docker deployments thanks to nginx proxying.
This setup makes it straightforward to deploy Invoice Builder on a home server, NAS, or cloud VM.
Verdict: who should consider Invoice Builder
Invoice Builder is a solid choice for freelancers and small businesses who want full control over their invoicing data without relying on cloud subscriptions. Its offline-first Electron app with a robust local SQLite database makes it usable even without internet connectivity.
The dual-database architecture and Docker multi-user support add flexibility and scalability without fragmenting the codebase. Compliance with European e-invoicing standards and multi-currency support make it relevant for international users and those with regulatory needs.
The memory and disk footprint reflect the complexity of the features and Electron base — it’s not for ultra-lightweight scenarios. Users comfortable with Docker and self-hosting will appreciate the clear deployment options.
In short, Invoice Builder solves a real problem with a pragmatic, well-engineered approach. It’s worth understanding for anyone building invoicing tools or seeking a self-hosted, offline-capable invoicing solution with multi-user support.
Related Articles
- Trilium Notes: a self-hosted hierarchical note-taking system with rich scripting and synchronization — Trilium Notes offers a rich TypeScript/Electron desktop experience for hierarchical note-taking with self-hosted sync an
- Memos: a self-hosted note-taking tool with radical simplicity in Go — Memos is a Go-based self-hosted note-taking app with a single binary and lightweight Docker image. It supports Markdown
- Supabase: composable open-source backend-as-a-service built around Postgres — Supabase combines specialized open-source tools around Postgres to offer a Firebase-like backend platform. Its modular a
→ GitHub Repo: piratuks/invoice-builder ⭐ 430 · TypeScript