lpdev - Laravel Package Development CLI

A powerful CLI tool for managing Laravel package development workflows. Streamline your local package development with automated symlink management, development server orchestration, and convenient shortcuts.

Features

• 🔗 Symlink Management: Automatically link/unlink local packages to Laravel projects
• 🚀 Development Server Management: Start Laravel and npm dev servers with tmux integration
• 📦 Project Organization: Manage multiple Laravel projects and packages
• ⚡ Quick Commands: Shortcuts for common artisan and npm commands
• 🔄 Context Switching: Easily switch between different projects

Installation

Via npm (Recommended)

npm install -g lpdev

Or with yarn:

yarn global add lpdev

Manual Installation

git clone https://github.com/yourusername/lpdev.git
cd lpdev
npm install -g .

Quick Start

1. Add a Laravel Project

lpdev add
# Follow the prompts to configure your project

2. Link Your Package for Development

lpdev link
# This creates a symlink from your Laravel app to your local package

3. Start Development Servers

lpdev start
# Starts both Laravel and npm dev servers in tmux panes

Commands

Project Management

Command	Description
lpdev add	Add a new Laravel project configuration
lpdev list	List all configured projects
lpdev use <project>	Switch to a different project
lpdev remove <project>	Remove a project configuration
lpdev current	Show current active project

Package Development

Command	Description
lpdev link	Create symlink to local package
lpdev unlink	Remove package symlink
lpdev status	Show link status

Development Servers

Command	Description
lpdev dev	Start full development environment (server, queue, logs, vite)
lpdev dev --exclude=service1,service2	Start dev environment excluding specified services
lpdev start laravel	Start only Laravel server
lpdev start npm	Start only npm dev server
lpdev stop	Stop all servers

Shortcuts

Command	Alias	Description
lpdev artisan <command>	lpdev a	Run artisan command in Laravel app
lpdev app <command>	-	Run command in app directory
lpdev pkg <command>	-	Run command in package directory
lpdev composer <command>	lpdev c	Run composer in app directory

Configuration

Configuration files are stored in ~/.lpdev/:

• projects.json - Project configurations
• current_project - Current active project

Project Configuration Structure

{
  "my-project": {
    "app_path": "/path/to/laravel/app",
    "package_path": "/path/to/local/package",
    "vendor_name": "vendor-name",
    "package_name": "package-name",
    "app_url": "http://localhost:8000",
    "npm_dev_port": 5173
  }
}

Environment Variables

LPDEV supports project-specific environment variables stored in your project configuration:

LPDEV Project Environment Variables

Manage lpdev project configuration with these commands:

• lpdev env-set <key> <value> - Set project environment variable
• lpdev env-remove <key> - Remove project environment variable
• lpdev env-list - List all project environment variables

Variable	Description	Default
QUEUE_NAME	Specific queue name to listen to (only for queue:listen)	Uses default queue
EXCLUDE	Default services to exclude from lpdev dev	None excluded

Setting Default Exclusions

# Exclude specific services by default for this project
lpdev env-set EXCLUDE "logs,vite"

# Set custom queue name
lpdev env-set QUEUE_NAME "high-priority"

# List current project environment variables
lpdev env-list

# Remove environment variable
lpdev env-remove EXCLUDE

Service Exclusion

The lpdev dev command supports excluding specific services with the --exclude flag:

Available Services:

• server - Laravel development server (php artisan serve)
• queue - Queue worker (Horizon or queue:listen)
• logs - Log tailing (php artisan pail) - Laravel 11+ only
• reverb - Laravel Reverb WebSocket server (php artisan reverb:start)
• vite - Vite dev server from package (npm run dev)

Command Line Examples:

lpdev dev --exclude=queue          # Skip queue worker
lpdev dev --exclude=queue,logs     # Skip queue and logs

Setting Default Exclusions: You can set default exclusions via lpdev project configuration:

# Set via lpdev project configuration
lpdev env-set EXCLUDE "queue,logs"   # Always exclude queue and logs by default

With EXCLUDE set, running lpdev dev will automatically exclude those services. You can still override with the --exclude flag:

lpdev dev                        # Uses EXCLUDE from project config
lpdev dev --exclude=queue        # Overrides config, excludes only queue

Use Cases:

• Set EXCLUDE=queue if you prefer running lpdev horizon-watch separately
• Set EXCLUDE=logs if you prefer using external log viewers

Queue Management

The lpdev dev command automatically detects and uses the best queue management tool available:

1. Laravel Horizon with Watcher (if available): Runs lpdev horizon-watch. When using Horizon Watcher, make sure to exclude the horizon service from lpdev dev using --exclude=queue or setting EXCLUDE=queue in project config.
2. Laravel Horizon Runs php artisan horizon
3. Standard Queue: Falls back to php artisan queue:listen --tries=1

Horizon Watcher Benefits:

• Automatically restarts Horizon when configuration files change
• Perfect for development when tweaking queue settings
• No manual restarts needed when modifying config/horizon.php

If using standard queue:listen, you can specify a custom queue name:

# Set via lpdev project configuration
lpdev env-set QUEUE_NAME high-priority  # Will run: php artisan queue:listen --queue=high-priority --tries=1

Note: QUEUE_NAME is ignored when Horizon is detected, as Horizon manages its own queue configuration.

Plugin System

lpdev supports a powerful plugin system for extending functionality. Plugins can hook into various lpdev operations and add custom commands.

📚 Plugin Documentation - Complete guide to creating and using plugins

Requirements

• Bash 4.0+
• Node.js 14.0+
• Python3 (for JSON parsing)
• tmux (optional, for server management)
• Laravel application
• Composer installed globally

Platform Support

• ✅ macOS
• ✅ Linux
• ⚠️ Windows (via WSL/Git Bash - limited support)

Examples

Complete Workflow

# Add and configure a new project
lpdev add

# Link package for development
lpdev link

# Start full development environment (server, queue, logs, vite)
lpdev dev

# Run database migrations
lpdev artisan migrate

# Clear application cache
lpdev a cache:clear

# Build package assets
lpdev pkg npm run build

# Run tests in package
lpdev pkg composer test

# Stop servers and unlink when done
lpdev stop
lpdev unlink

Working with Multiple Projects

# List all projects
lpdev list

# Switch to different project
lpdev use my-other-project

# Show current project
lpdev current

Troubleshooting

Completion not working?

After installation, source your shell configuration:

source ~/.bashrc  # or ~/.zshrc for zsh

Permission Issues

Make sure the global npm directory is in your PATH:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Symlink Issues

If you encounter symlink problems:

1. Check package exists: lpdev status
2. Unlink and relink: lpdev unlink && lpdev link
3. Verify composer autoload: lpdev composer dump-autoload

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

LPDEV is licensed under the MIT License, sponsored and supported by Inovector.