Environment Management

Launchpad provides powerful environment management capabilities that automatically isolate project dependencies and provide tools for managing these environments. This guide covers all aspects of environment management, from automatic activation to manual cleanup.

Overview

Environment management in Launchpad consists of two main components:

Automatic Environment Isolation - Project-specific environments that activate when you enter a directory
Environment Management Tools - CLI commands for listing, inspecting, cleaning, and removing environments
Shell Message Customization - Configurable activation and deactivation messages

Automatic Environment Isolation

How It Works

When you enter a directory containing dependency files (like dependencies.yaml), Launchpad automatically:

Generates a unique environment hash based on the project path
Creates an isolated environment directory at ~/.local/share/launchpad/envs/{hash}/
Installs project-specific packages to the isolated environment
Modifies PATH to prioritize the project's binaries
Sets up environment variables as specified in the dependency file
Creates deactivation hooks to restore the original environment when leaving
Displays customizable messages for activation and deactivation

Environment Hash Format

Launchpad uses a human-readable hash format for environment directories:

Format: {project-name}_{8-char-hex-hash}

Examples:

my-web-app_1a2b3c4d - For a project in /home/user/projects/my-web-app
api-server_5e6f7g8h - For a project in /work/api-server
final-project_7db6cf06 - For a deeply nested project

Benefits:

Human-readable - Easy to identify which project an environment belongs to
Unique - 8-character hex hash prevents collisions between projects
Consistent - Same project path always generates the same hash
Collision-resistant - Different paths with same project name get different hashes

Supported Dependency Files

Launchpad automatically detects these dependency files:

dependencies.yaml / dependencies.yml
.launchpad.yaml / launchpad.yaml
.launchpad.yml / launchpad.yml
deps.yml / deps.yaml
.deps.yml / .deps.yaml

For pkgx compatibility, Launchpad also supports:

pkgx.yaml / pkgx.yml
.pkgx.yaml / .pkgx.yml

Example dependency file:

yaml

dependencies:
  - node@22
  - python@3.12
  - gnu.org/wget@1.21

env:
  NODE_ENV: development
  API_URL: https://api.example.com
  DATABASE_URL: postgresql://localhost/myapp

Shell Integration

To enable automatic environment activation, add shell integration:

bash

# Add to your shell configuration
echo 'eval "$(launchpad dev:shellcode)"' >> ~/.zshrc

# Reload your shell
source ~/.zshrc

Once set up, environments automatically activate:

bash

cd my-project/  # → ✅ Environment activated for /path/to/my-project
cd ../          # → dev environment deactivated

Customizing Shell Messages

You can customize or disable environment activation/deactivation messages:

Disabling Messages

bash

# Disable all environment messages
export LAUNCHPAD_SHOW_ENV_MESSAGES=false

# Or in configuration file
echo 'export default { showShellMessages: false }' > launchpad.config.ts

Custom Activation Messages

bash

# Environment variable (use {path} placeholder for project path)
export LAUNCHPAD_SHELL_ACTIVATION_MESSAGE="🚀 Project environment loaded: {path}"

# Or in configuration file
echo 'export default {
  shellActivationMessage: "🔧 Development environment ready: {path}"
}' > launchpad.config.ts

Custom Deactivation Messages

bash

# Environment variable
export LAUNCHPAD_SHELL_DEACTIVATION_MESSAGE="👋 Project environment closed"

# Or in configuration file
echo 'export default {
  shellDeactivationMessage: "🔒 Environment closed"
}' > launchpad.config.ts

Message Examples

Different styles you can use:

bash

# Minimal style
export LAUNCHPAD_SHELL_ACTIVATION_MESSAGE="[ENV] {path}"
export LAUNCHPAD_SHELL_DEACTIVATION_MESSAGE="[ENV] closed"

# Detailed style
export LAUNCHPAD_SHELL_ACTIVATION_MESSAGE="🔧 Development environment ready for {path}"
export LAUNCHPAD_SHELL_DEACTIVATION_MESSAGE="👋 Development environment deactivated"

# Emoji style
export LAUNCHPAD_SHELL_ACTIVATION_MESSAGE="📁 {path} 🚀"
export LAUNCHPAD_SHELL_DEACTIVATION_MESSAGE="🏠 Back to global environment"