configuring-devenv

name	configuring-devenv
description	Initializes and configures devenv development environments. Searches packages, sets up languages, services, scripts, git hooks, and processes. Use when setting up devenv, adding packages to devenv.nix, configuring languages, services, git hooks, or searching for devenv options.

Devenv Configuration

Initializes, configures, and searches devenv development environments.

Your Task

Determine action from $ARGUMENTS or context:

Intent	Action
"init devenv", "set up devenv", "new devenv"	Initialize new project
"add package", "configure", "enable"	Modify configuration
"search", "find package", "how to add"	Search packages/options

Progress Checklist

• Determine action (init/config/search)
• Check current state
• Execute action
• Validate changes
• Guide next steps

---

Initializing Projects

Step 1: Check Prerequisites

# Check if devenv exists
test -f devenv.nix && echo "exists" || echo "new"

# Check if devenv is installed
devenv version

If not installed: curl -L https://get.devenv.sh | sh

Step 2: Detect Project Type

File	Project Type
package.json	Node.js
pyproject.toml, requirements.txt	Python
Cargo.toml	Rust
go.mod	Go
Multiple	Full-stack

Step 3: Create Configuration

Python:

{ pkgs, ... }:

{
  languages.python = {
    enable = true;
    version = "3.11";
    venv.enable = true;
  };

  scripts = {
    test.exec = "pytest";
    lint.exec = "ruff check .";
  };

  git-hooks.hooks = {
    black.enable = true;
    ruff.enable = true;
  };
}

Node.js:

{ pkgs, ... }:

{
  languages.javascript = {
    enable = true;
    npm.enable = true;  # or bun.enable
  };

  scripts = {
    dev.exec = "npm run dev";
    test.exec = "npm test";
  };

  git-hooks.hooks = {
    prettier.enable = true;
    eslint.enable = true;
  };
}

Rust:

{ pkgs, ... }:

{
  languages.rust.enable = true;

  packages = with pkgs; [ cargo-watch ];

  scripts = {
    dev.exec = "cargo watch -x run";
    test.exec = "cargo test";
  };

  git-hooks.hooks = {
    rustfmt.enable = true;
    clippy.enable = true;
  };
}

Go:

{ pkgs, ... }:

{
  languages.go.enable = true;

  packages = with pkgs; [ golangci-lint air ];

  scripts = {
    dev.exec = "air";
    test.exec = "go test ./...";
  };

  git-hooks.hooks = {
    gofmt.enable = true;
    govet.enable = true;
  };
}

Step 4: Create Supporting Files

.envrc:

use devenv

.gitignore additions:

.devenv*
devenv.lock
.direnv

Step 5: Validate

nix-instantiate --parse devenv.nix
devenv info
direnv allow

---

Configuring Projects

Always Read First

cat devenv.nix

Languages

languages = {
  javascript = {
    enable = true;
    npm.enable = true;      # or bun.enable, pnpm.enable
  };
  python = {
    enable = true;
    version = "3.11";
    venv.enable = true;
  };
  rust.enable = true;
  go.enable = true;
};

Packages

packages = with pkgs; [
  gh            # GitHub CLI
  jq            # JSON processor
  docker
  kubectl
];

Scripts

scripts = {
  dev.exec = "npm run dev";
  test.exec = "pytest tests/";
  db-reset.exec = ''
    dropdb myapp --if-exists
    createdb myapp
  '';
};

Git Hooks

git-hooks.hooks = {
  prettier.enable = true;
  eslint.enable = true;
  black.enable = true;
  rustfmt.enable = true;
  shellcheck.enable = true;
  gitleaks.enable = true;
};

Services

services = {
  postgres = {
    enable = true;
    initialDatabases = [{ name = "myapp_dev"; }];
  };
  redis.enable = true;
  mysql.enable = true;
};

Processes

processes = {
  backend.exec = "uvicorn main:app --reload";
  frontend.exec = "npm run dev";
};

Start all with devenv up.

Environment Variables

env = {
  DATABASE_URL = "postgresql://localhost/myapp";
  API_KEY = "dev-key";
};

Validation After Changes

nix-instantiate --parse devenv.nix
devenv info
direnv reload

---

Searching Packages/Options

Using CLI

devenv search <query>

Using MCP Tools

Use mcp__mcp_devenv_sh__search_packages and mcp__mcp_devenv_sh__search_options.

Common Corrections

User Types	Search For
node, npm	nodejs
pg, postgresql	postgres
k8s	kubectl
python3	python
mongo	mongodb

Present Results

## Search Results for "{query}"

### Configuration Options
| Option | Description |
|--------|-------------|
| `languages.python.enable` | Enable Python support |

### Packages
| Package | Description |
|---------|-------------|
| `python311` | Python 3.11 interpreter |

### Usage Example
(show nix snippet)

---

Full-Stack Configuration

For frontend + backend + database:

{ pkgs, ... }:

{
  languages = {
    javascript = {
      enable = true;
      npm.enable = true;
    };
    python = {
      enable = true;
      version = "3.11";
      venv.enable = true;
    };
  };

  env = {
    DATABASE_URL = "postgresql://localhost:5432/myapp_dev";
    API_URL = "http://localhost:8000";
  };

  services.postgres = {
    enable = true;
    initialDatabases = [{ name = "myapp_dev"; }];
  };

  processes = {
    backend = {
      exec = "cd backend && uvicorn main:app --reload --port 8000";
      process-compose = {
        depends_on.postgres.condition = "process_healthy";
      };
    };
    frontend = {
      exec = "cd frontend && npm run dev";
      process-compose = {
        depends_on.backend.condition = "process_healthy";
      };
    };
  };

  scripts = {
    dev.exec = "devenv up";
    db-reset.exec = ''
      dropdb myapp_dev --if-exists
      createdb myapp_dev
    '';
  };

  git-hooks.hooks = {
    prettier.enable = true;
    black.enable = true;
  };
}

---

Error Handling

Issue	Solution
devenv not found	curl -L https://get.devenv.sh | sh
Syntax error	nix-instantiate --parse devenv.nix
Package not found	Search with MCP tools or devenv search
Changes not appearing	direnv reload or restart shell
Service won't start	Check $DEVENV_STATE logs
Port in use	lsof -i :<port> to find process
Hook not running	devenv gc && direnv allow

---

Tips

• Always read devenv.nix before editing
• Use MCP search tools to find correct names
• Prefer languages.* over adding interpreter packages
• Use services.* for databases (auto-configured)
• Use processes for multi-service development
• Test changes with devenv info after editing
• Scripts become shell commands automatically