Nix Development Environment
Relevant source files
The following files were used as context for generating this wiki page:
The Nix Development Environment for the ProductCompare project provides a reproducible, isolated, and standardized toolchain for both backend and frontend development. It ensures that all contributors use identical versions of the Elixir runtime, Erlang/OTP, and supporting system dependencies, regardless of their local operating system.
The environment is primarily accessed through a Nix development shell, which integrates with Docker Compose to manage the containerized PostgreSQL database. This setup allows developers to move from a fresh clone to a running application with a single command, maintaining consistency across local development and CI environments.
Sources: README.md:1-20, 2026-03-03-product-compare-backend-mvp-plan.md:17-20
Core Toolchain and Stack
The environment provides the specific versions of the software stack required for the modular-monolith architecture. This includes the functional programming environment for the Elixir backend and the JavaScript runtime for the React-based frontend.
| Component | Version | Description |
|---|---|---|
| Elixir | 1.19.x | Backend programming language |
| Erlang/OTP | 28 | Concurrent runtime system |
| Phoenix | 1.8.x | Web framework for Elixir |
| PostgreSQL | 18 | Relational database (via Docker) |
| Bun | (Used in assets/) | JS runtime and package manager |
| Vite | (Used in assets/) | Frontend build tool |
Sources: README.md:5-10, assets/package.json:5-15, 2026-03-03-product-compare-backend-mvp-plan.md:17-20
Shell Initialization and Workflow
The development workflow is designed to be executed within the Nix shell to ensure that mix and bun commands use the project-defined versions of their respective runtimes.
The diagram shows the standard sequence for preparing the development environment.
Sources: README.md:12-23, 2026-03-03-product-compare-backend-mvp-plan.md:65-75
Development Commands
Developers interact with the environment through standardized mix aliases that gate various stages of the development lifecycle:
mix setup: Installs dependencies and prepares the database.mix test: Runs the test suite across all context boundaries.mix typecheck: Executesdialyzerand strict typespec checks.mix precommit: A hard gate that runs formatting, tests, and typechecks; used to ensure code quality before PR submission.mix ci: Executes the full suite of checks required for continuous integration.
Sources: README.md:33-38, backend_starting_guide.md:213-220
Environment Configuration
The Nix shell manages environment variables and paths necessary for the application to interact with its infrastructure. A critical component is the configuration of the PostgreSQL connection, which defaults to localhost:5433 to match the mapping defined in the project's Docker Compose configuration.
Infrastructure Integration
While Nix manages the runtimes, Docker Compose is utilized for stateful infrastructure that is better suited for containerization than pure Nix packages.
This diagram illustrates the relationship between the Nix-managed runtimes and the containerized database.
Sources: README.md:5-25, ARCHITECTURE.md:10-15, 2026-03-03-product-compare-backend-mvp-plan.md:78-85
Implementation Artifacts
The Nix environment is defined and supported by several key files in the repository root:
flake.nix: The primary entry point for Nix Flakes, defining the system packages and development shell.flake.lock: Locks the exact versions of the Nix packages for reproducibility.docker-compose.yml: Defines the PostgreSQL 18 service, including health checks and persistent volumes..env.example: Provides a template for local environment variables, such asDATABASE_URL.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:92-95
Summary
The Nix Development Environment provides a rigid yet easy-to-use foundation for the ProductCompare modular monolith. By pinning specific versions of Elixir (1.19.x) and Erlang (28) and providing a containerized PostgreSQL 18 instance, the project eliminates "it works on my machine" issues and streamlines the onboarding process for new developers.