dev-rs 0.2.3

The missing tool for 12 factor development environments

Dev tool

This tool provides a standard interface to manage 12 factor projects, regardless of the language or framework used. The main goal is to allow you to run a standard set of commands for common tasks, which just work™ is any supported repo, such as:

• Manage encrypted environment variables
• Run a command in an environment
• Start up a full webserver in an environment
• Connect to an environments database

What are environments?

When manage an application, your normally require multiple environment, normally at least production, and development. On top of that, you'll probably need some form of local environment, so that you can run and test your application, with similar settings to production.

In environments, we attempt to capture all dependencies required to have your application up and running. The two key components are environment variables and external packages. The external packages used between each environment is the same, and the only difference are the environment variables.

In order to run a command within the default local environment, you can use the following:

dev run <command>

This will make sure that all packages are automatically installed, and all environment variables are exported for your command.

Sometimes you may want to run a one-off command in your local system, but connected to other production services (such as your database), or with production settings. To do this, you can run the following:

dev run -e prd <command>

External packages

Whenever you deploy your application to production, it's good practise to lock down external package to specific versions so you're able to recreate it if required. In development environments, you are often just left following a (hopefully) documented set of instructions to get your local system (mostly) in sync with production. These can be useful on a fresh system, but get complicated quickly when working on multiple products with different versions of packages required. Even worse, you might be gradually doing upgrades between OS releases across your team, and having conflict between the new packages, and the old one.

dev allows you to use various tools to maintain external packages:

• The Nix package manager resolves this issue with system level packages, by downloading and making programs and libraries available while within dev run or dev start. This can be used to automatically set up a certain version of nodejs, python or rust tools.
• Your language-specific package manager, such as poetry, uv, or npm, can resolve this issue for all packages managed by the language's traditional package repository.

To set these up, you'll need to add this config to your .dev/config.toml:

[commands]
# Just use a nix environment
shell = 'nix develop -c -- "$@"'
# Just use a uv environment
shell = 'uv run -- "$@"'
# Use both nix and uv environments together
shell = 'nix develop -c -- uv run -- "$@"'

Environment variables

This is a hard one, particularly when it comes to local development. It's not uncommon to see a local .env file, manually copied between developers, across questionable mediums. If you're anything like me, you're probably getting major there must be a better way! syndrome.

In dev, we use instead manage environment variables the same way for production and local development. We create an encrypted file per environment that contains all environment variables required to run the application. This allows you to track all changes in version control, as if they were regular code changes. It also means you can include environment variable deployments into CI/CD pipelines, rather than managing them manually.

To modify your environment variables using your default, you can use the command:

dev config edit [-e env]

Getting started

To set up the dev command in you repo, run the following command and follow the prompts. This will set your .dev/config.toml with enough details to get you started.

dev init

Commands

Run a command with environment variables

dev run [-e env] <command> [args...]

Start the development environment

This runs the command configured to start up the main service for this application. If you want to run multiple services, you can try configuring it to run something like process-compose.

dev start [-e env]

Manage configuration

Edit the environment configuration:

dev config edit [-e env]

Export the configuration:

dev config export [-e env] [--format <format>]

Available formats: raw, json, docker.

Connect to a PostgreSQL database

When working on an application that requires a PostgreSQL database, you commonly need to run queries on databases across different environments. The dev tools makes this easier by allowing you to track these credentials using the DATABASE_URL environment variable. You can then use the following commands to run an interactive psql prompt without needing to manually handle database credentials across your team:

# Connect to the local environment's database
dev psql

# Connect to the dev environment's databse
dev psql -e dev