Getting started

Welcome to jpd! This tutorial will get you up and running in just a few minutes. By the end, you’ll understand how to install jpd, detect your package manager, and use the most common commands.

Installation

jpd is distributed as a single binary and can be installed via popular package managers:

macOS/Linux (Homebrew)

brew install louiss0/tap/jpd

Windows (Scoop)

scoop bucket add louiss0 https://github.com/louiss0/scoop-bucket.git
scoop install jpd

Windows (Winget)

winget install jpd

Manual Installation

1. Visit the releases page
2. Download the appropriate binary for your operating system:
   • jpd-linux-amd64 for Linux x64
   • jpd-darwin-amd64 for macOS Intel
   • jpd-darwin-arm64 for macOS Apple Silicon
   • jpd-windows-amd64.exe for Windows x64
3. Rename the binary to jpd (or jpd.exe on Windows)
4. Make it executable: chmod +x jpd (Linux/macOS)
5. Move it to a directory in your PATH (e.g., /usr/local/bin, ~/bin)

Nix

# Install via Nix profile (recommended)
nix profile install github:nix-community/nur#repos.the-code-fixer-23-nur.jpd

# Build via default.nix and install locally
nix-build default.nix -A jpd
# Symlink into your PATH (example)
install -Dm755 ./result/bin/jpd ~/.local/bin/jpd

# Or use a temporary shell with jpd available
nix-shell -p "(import ./default.nix {}).jpd"

Tip

Once installed, run jpd --version to verify the installation was successful.

Basic Workflow

1. Detect your package manager

   Navigate to any JavaScript project and run:

   jpd agent

   This shows which package manager jpd detected for your project. It will show something like npm, yarn, pnpm, bun, or deno.

2. Install dependencies

   Instead of remembering whether to run npm install, yarn install, or pnpm install, just run:

   jpd install

   jpd automatically delegates to the correct package manager based on your project’s lock files.

3. Run scripts interactively

   To see all available scripts and select one:

   jpd run

   Or run a specific script directly:

   jpd run dev
   jpd run build
   jpd run test

4. Execute packages

   Instead of npx, yarn dlx, pnpm dlx, or bunx:

   jpd exec create-react-app my-app
   jpd exec typescript --version
   jpd exec prettier --check .

Common Tasks

Adding Dependencies

Add packages to your project:

# Add a regular dependency
jpd install lodash

# Add a development dependency
jpd install -D vitest

# Add multiple packages
jpd install react react-dom

Note

jpd automatically uses the correct flags for each package manager:

• npm: --save-dev
• yarn: --dev
• pnpm: --save-dev
• bun: --development

Interactive Package Search

Search the npm registry and select packages interactively:

jpd install -s react

This opens an interactive interface where you can search for packages and select which ones to install.

Scaffolding New Projects

Create new projects using create runners from various package managers:

# Create a React app
jpd create react-app my-app

# Create a Vite project with a template
jpd create vite@latest my-project -- --template react-swc

# Create a Next.js app
jpd create next-app my-next-app --typescript

For Deno projects, use URLs instead of package names:

# Create a Fresh project (Deno)
jpd -a deno create https://deno.land/x/fresh/init.ts my-fresh-app

Note

jpd automatically adds the create- prefix for npm, pnpm, yarn, and bun. Deno requires a valid URL to a TypeScript initialization script.

Updating Dependencies

Update all dependencies to their latest compatible versions:

jpd update

Removing Dependencies

Remove packages from your project:

# Remove specific packages
jpd uninstall lodash

# Interactive removal - select packages to remove
jpd uninstall -i

Clean Install for CI/CD

Perform a clean installation with frozen lockfiles (ideal for CI environments):

jpd clean-install

This maps to the appropriate command for each package manager:

• npm: npm ci
• yarn v1: yarn install --frozen-lockfile
• yarn v2+: yarn install --immutable
• pnpm: pnpm install --frozen-lockfile
• bun: bun install --frozen-lockfile

Advanced Usage

Override the Agent

Sometimes you might want to force a specific package manager:

# Use yarn even if npm is detected
jpd install --agent yarn

# Set for entire session
export JPD_AGENT=yarn
jpd install

Run Commands in Subprojects

Execute commands in different directories without changing your shell’s working directory:

# Install dependencies in a subdirectory
jpd install --cwd ./my-frontend-app/

# Run build script in a subdirectory
jpd run --cwd ./packages/ui/ build

Trailing Slash Requirement

The --cwd flag requires paths to end with / (except for root /). In CI builds compiled with the CI flag, both path and path/ are accepted.

Debug Mode

See exactly what commands jpd is executing:

jpd install --debug
jpd run build --debug

This shows detailed logging about package manager detection and the actual commands being run.

Shell Completion

Enable tab completion for your shell:

# Bash
jpd completion bash > /etc/bash_completion.d/jpd

# Zsh (add to .zshrc)
jpd completion zsh > ~/.zsh/completions/_jpd

# Fish
jpd completion fish > ~/.config/fish/completions/jpd.fish

# Nushell (with output flag)
jpd completion nushell --output ~/.config/nushell/completions/jpd_completions.nu

What’s Next?

Now that you’ve mastered the basics, explore these advanced topics:

• Interactive Workflows - Learn about interactive package search and dependency management
• Working with Subprojects - Master the --cwd flag for monorepos
• Agent Override - Control which package manager to use
• Complete Command Reference - Browse all available commands and flags

Note

Having trouble? Use the jpd agent command to see which package manager jpd detected, or try the --debug flag to see detailed detection information.