Skip to content

stacksjs/launchpad

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

65 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Social Card of this repo

npm version GitHub Actions Commitizen friendly

launchpad

A modern dependency manager for your system and projects. Effortlessly manage development tools, runtime environments, and project dependencies with automatic environment isolation. Think Homebrew meets project-aware dependency management.

What is Launchpad?

Launchpad is a comprehensive dependency management solution that bridges the gap between system-wide package management and project-specific environments. Whether you're setting up a new development machine, managing system tools, or working on projects with specific dependency requirements, Launchpad provides a unified interface for all your dependency needs.

System Management:

  • Install and manage development tools system-wide
  • Automatic PATH configuration and shell integration
  • Cross-platform compatibility (macOS, Linux, Windows)
  • Smart permission handling and installation paths

Project Management:

  • Automatic project environment detection and activation
  • Isolated dependency environments per project
  • Version-specific tool installation
  • Seamless switching between project contexts

At its core, Launchpad leverages pkgx's powerful package ecosystem while adding intelligent management, environment isolation, and developer-friendly workflows.

Features

Launchpad transforms how you manage dependencies across your entire development workflow:

System-Wide Dependency Management

  • πŸ“¦ Global Tool Installation β€” Install development tools and runtimes system-wide with automatic PATH management
  • πŸ”§ Smart Installation Paths β€” Automatically chooses /usr/local for system-wide access or ~/.local for user-specific installs
  • πŸ”Œ Shell Integration β€” Seamless integration with your shell for immediate tool availability
  • πŸͺŸ Cross-Platform Support β€” Consistent experience across macOS, Linux, and Windows

Project-Aware Environment Management

  • 🌍 Automatic Environment Isolation β€” Project-specific environments that activate when you enter a project directory
  • 🎯 Dependency Detection β€” Automatically reads dependencies.yaml, package.json, and other project files
  • πŸ”„ Context Switching β€” Seamlessly switch between different project environments
  • πŸ“‹ Version Management β€” Install and manage specific versions of tools per project
  • πŸ—‚οΈ Environment Management β€” List, inspect, clean, and remove project environments with readable identifiers

Developer Experience

  • ⚑ Fast Operations β€” Leverage pkgx for efficient package management
  • πŸ—‘οΈ Clean Removal β€” Remove packages or completely uninstall with proper cleanup
  • πŸ”„ Auto-Updates β€” Configure automatic updates for your dependency management tools
  • πŸŽ›οΈ Flexible Configuration β€” Customize behavior through config files or command-line options

Why Launchpad?

Modern development requires managing dependencies at multiple levels - from system tools to project-specific requirements. Traditional approaches fall short:

Traditional Package Managers (Homebrew, apt, etc.):

  • ❌ Global conflicts β€” Different projects need different versions
  • ❌ Slow operations β€” Installing or updating can take minutes
  • ❌ Manual environment management β€” Switching between project contexts is manual
  • ❌ PATH pollution β€” All tools are globally available, causing conflicts

Manual Dependency Management:

  • ❌ Inconsistent setups β€” Different team members have different environments
  • ❌ Complex PATH management β€” Manual shell configuration is error-prone
  • ❌ Version drift β€” Hard to maintain consistent tool versions
  • ❌ Platform differences β€” Different setup procedures for each OS

Launchpad's Solution:

  • βœ… Unified Management β€” Single tool for both system and project dependencies
  • βœ… Automatic Isolation β€” Project environments activate automatically
  • βœ… Fast Operations β€” Efficient package management with intelligent caching
  • βœ… Consistent Experience β€” Same commands and behavior across all platforms
  • βœ… Smart Defaults β€” Sensible installation paths and configuration out of the box

Read more about why we created Launchpad

Installation

Get started with Launchpad through your preferred package manager:

# Install with Bun (recommended)
bun add -g @stacksjs/launchpad

# Or with npm
npm install -g @stacksjs/launchpad

# Or with yarn
yarn global add @stacksjs/launchpad

# Or with pnpm
pnpm add -g @stacksjs/launchpad

See Installation Guide for more options.

Quick Start

Launchpad is designed to handle both system setup and project management seamlessly! 🎯

System Setup (First Time)

Bootstrap your development environment with everything you need:

# Complete system setup - installs to /usr/local by default
./launchpad bootstrap

# Or for a custom installation path
./launchpad bootstrap --path ~/.local --verbose

# Skip specific components if needed
./launchpad bootstrap --skip-bun --skip-shell-integration

The bootstrap command sets up your entire development foundation:

  • βœ… Install pkgx (package manager)
  • βœ… Install Bun (JavaScript runtime)
  • βœ… Configure your PATH automatically
  • βœ… Set up shell integration for project auto-activation
  • βœ… Provide clear next steps

System-Wide Tool Management

Install and manage development tools across your entire system:

# Install essential development tools system-wide
launchpad install node python go rust

# Install specific versions
launchpad install node@22 python@3.12

# Install to /usr/local (default system-wide location)
launchpad install typescript --system

# Or specify any custom path
launchpad install docker --path /opt/tools

# Use shorthand for quick installs
launchpad i node@22 typescript@5.7

Smart Installation Behavior:

  • Default: Installs to /usr/local if writable, otherwise ~/.local
  • System-wide: Use --system for explicit system installation (same as default)
  • Custom paths: Use --path <directory> for any location
  • Automatic PATH: Tools are immediately available in new shells

Project Environment Management

Launchpad automatically manages project-specific dependencies:

# Create a project with dependencies
echo "dependencies:
  - node@22
  - typescript@5.7
  - bun@1.2" > dependencies.yaml

# Environment activates automatically when you enter the directory
cd my-project
# β†’ βœ… Environment activated for /path/to/my-project

# Tools are available in project context
node --version  # Uses project-specific Node.js
tsc --version   # Uses project-specific TypeScript

# Leave project - environment deactivates automatically
cd ..
# β†’ πŸ”„ Environment deactivated

Supported Project Files:

  • dependencies.yaml / dependencies.yml
  • package.json (Node.js projects)
  • pyproject.toml (Python projects)
  • Cargo.toml (Rust projects)
  • And more...

Environment Management

Manage your project environments with human-readable identifiers:

# List all development environments
launchpad env:list

# Inspect a specific environment
launchpad env:inspect my-project_1a2b3c4d

# Clean up old or failed environments
launchpad env:clean --dry-run

# Remove a specific environment
launchpad env:remove old-project_5e6f7g8h --force

Environment Hash Format: {project-name}_{8-char-hex}

  • final-project_7db6cf06 - Easy to identify and manage
  • working-test_208a31ec - Human-readable project identification
  • my-app_1a2b3c4d - Collision-resistant unique identifiers

Package Management

Remove packages and manage your installation:

# Remove specific system tools
launchpad remove node python

# Remove project-specific versions
launchpad rm node@22

# See what would be removed
launchpad remove python --dry-run

# Complete system cleanup
launchpad uninstall

Advanced Operations

# Create executable shims
launchpad shim node@22 typescript@5.7

# List all installed packages
launchpad list

# Configure auto-updates
launchpad autoupdate:enable

# Install additional tools
launchpad pkgx    # Install pkgx itself
launchpad dev     # Install dev environment tools
launchpad bun     # Install Bun runtime

Configuration

Customize Launchpad's behavior for your system and projects:

import type { LaunchpadConfig } from '@stacksjs/launchpad'

const config: LaunchpadConfig = {
  // System-wide installation preferences
  installationPath: '/usr/local', // Default system location
  autoSudo: true, // Auto-elevate when needed

  // Project environment settings
  autoActivate: true, // Auto-activate project environments
  symlinkVersions: true, // Create version-specific symlinks

  // Development preferences
  verbose: true, // Detailed logging
  maxRetries: 3, // Retry failed operations
  timeout: 60000, // Operation timeout

  // PATH and shell integration
  shimPath: '~/.local/bin', // Custom shim location
  autoAddToPath: true, // Automatic PATH management
}

export default config

See Configuration Guide for all options.

GitHub Action

Integrate Launchpad into your CI/CD workflows:

- name: Setup Development Environment
  uses: stacksjs/launchpad-installer@v1
  with:
    packages: node@22 typescript@5.7 bun@1.2.14

See GitHub Action Documentation for details.

Advanced Usage

Explore advanced dependency management topics:

Comparing to Alternatives

vs Traditional Package Managers (Homebrew, apt, yum)

  • 🎯 Project Awareness: Automatic project environment management vs manual setup
  • ⚑ Speed: Faster installations with intelligent caching
  • πŸ”’ Isolation: Project-specific versions vs global conflicts
  • 🌍 Cross-Platform: Consistent experience across all operating systems

vs Language-Specific Managers (nvm, pyenv, rbenv)

  • πŸ”„ Unified Interface: Single tool for all languages vs multiple managers
  • πŸ€– Automatic Switching: Context-aware environment activation
  • πŸ“¦ Broader Scope: Manages system tools beyond just language runtimes
  • πŸ› οΈ Integrated Workflow: Seamless integration between system and project dependencies

vs Container-Based Solutions (Docker, devcontainers)

  • πŸš€ Lightweight: Native performance without virtualization overhead
  • πŸ’» System Integration: Tools available in your native shell and IDE
  • πŸ”§ Flexible: Mix system-wide and project-specific tools as needed
  • ⚑ Instant: No container startup time or resource overhead

Changelog

Please see our releases page for information on changes.

Contributing

Please see CONTRIBUTING for details.

Community

For help or discussion:

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

License

The MIT License (MIT). Please see LICENSE for more information.

Made with πŸ’™

About

Similar to Homebrew, just faster. Powered by pkgx.

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Contributors 2

  •  
  •