Development Environments

Grove solves the “it works on my machine” problem by creating development environments that work exactly the same way on every computer. Here’s how it all works under the hood.

How Grove creates environments

Grove uses the Nix ecosystem and devenv to create completely isolated development environments. When you run kanuka grove init, several things happen:

1. Grove creates a devenv.nix file that declares what’s in your environment.
2. Grove creates a devenv.yaml file that tells devenv where to get packages from.
3. Grove creates a kanuka.toml file to track what it has added to your environment.
4. Grove updates your .gitignore to exclude build artifacts.

The files Grove creates

devenv.nix

This is the heart of your development environment - a file written in the Nix language that defines all the packages, languages, and services your project needs (devenv.nix reference):

{ pkgs, ... }: {
  # Packages managed by Kānuka Grove
  packages = [
    pkgs.nodejs_18
    pkgs.python3
    pkgs.git
  ];

  # Languages (also managed by Grove)
  languages.typescript.enable = true;

  # Services and additional configuration
  services.postgres.enable = true;
}

kanuka.toml

This is Kānuka’s own configuration file where it keeps track of what you’ve added:

[grove]
packages = ["nodejs_18", "python3", "git"]
languages = ["typescript"]

devenv.yaml

This file tells devenv where to get packages from (devenv inputs reference):

inputs:
  nixpkgs:
    url: github:NixOS/nixpkgs/nixpkgs-unstable

Why Grove environments are isolated

One of the best things about Grove is that your environments are completely separate from your system:

• No system dependencies: Everything your project needs is declared in devenv.nix.
• Clean PATH: Only the packages you’ve added are available.
• Reproducible: You get the same environment on every machine.
• Project-specific: Each project has its own environment that doesn’t interfere with others.

How environment isolation works

When you run kanuka grove enter, Grove creates a new shell environment where:

1. PATH is controlled: Only packages declared in your environment are available.
2. Environment variables are set: Each package can set its own environment variables.
3. Dependencies are resolved: All package dependencies are automatically included.
4. System is protected: Your system packages remain untouched.

This means you can have Python 3.9 in one project and Python 3.11 in another, without any conflicts.

Environment lifecycle

Initialization

When you run kanuka grove init, Grove sets up the foundation files but doesn’t install anything yet.

Package addition

When you run kanuka grove add <package>, Grove:

1. Updates devenv.nix with the new package.
2. Updates kanuka.toml to track the addition.
3. The environment is ready for the next time you enter it.

Environment entry

When you run kanuka grove enter, devenv:

1. Reads your devenv.nix configuration.
2. Downloads any missing packages from the Nix binary cache.
3. Creates an isolated shell with only your declared packages.
4. Sets up all necessary environment variables.

Updates

When you update channels or packages, Grove rebuilds the environment with the new versions while maintaining the same isolation guarantees.

Continue reading to learn about how package management works in Grove.