@scriptgun/crossdeps

Cross-platform system dependency manager. Define your project's system dependencies in a config file, then install them on any OS with a single command.

Install

npm install -D @scriptgun/crossdeps
# or
bun add -D @scriptgun/crossdeps

Quick Start

Create crossdeps.config.ts in your project root:

import { defineConfig } from "@scriptgun/crossdeps"

export default defineConfig({
  packageJsonPath: "package.json",
  deps: {
    node: {
      description: "JavaScript runtime",
      required: true,
      version: "22.12.0",
      os: {
        macos: "curl -fsSL https://nodejs.org/dist/v{{version}}/node-v{{version}}-darwin-{{arch}}.tar.gz | sudo tar -xz -C /usr/local --strip-components=1",
        "linux-apt": "curl -fsSL https://nodejs.org/dist/v{{version}}/node-v{{version}}-linux-x64.tar.gz | sudo tar -xz -C /usr/local --strip-components=1",
        windows: "choco install nodejs --version={{version}}",
      },
    },
    bun: {
      description: "JavaScript runtime and package manager",
      required: true,
      version: "1.3.5",
      os: {
        all: "curl -fsSL https://bun.sh/install | bash -s \"bun-v{{version}}\"",
        windows: "powershell -c \"irm bun.sh/install.ps1|iex\" && bun upgrade --to {{version}}",
      },
    },
  },
})

CLI Usage

# Install all dependencies
npx crossdeps install

# Install a single dependency
npx crossdeps install node

# Check installed versions
npx crossdeps check

# Check a single dependency
npx crossdeps check bun

# Setup environment variables (for deps that define env)
npx crossdeps env

# Sync packageManager field in package.json (for bun)
npx crossdeps sync-pm

# Use a custom config path
npx crossdeps install --config ./my-config.ts

Config Reference

defineConfig(options)

| Field | Type | Description | |-------|------|-------------| | packageJsonPath | string? | Path to package.json for sync-pm. Default: "package.json" | | deps | Record<string, SystemDepConfig> | Map of dependency name to config |

SystemDepConfig

| Field | Type | Description | |-------|------|-------------| | description | string | Human-readable description | | required | boolean | Whether installation failure should exit with error | | version | string | Version string (or "latest") | | os | OsCommands | Per-OS install commands | | check | { command: string }? | Custom version check command. Default: "{{name}} --version" | | dependsOn | string[]? | Deps that must be installed first (by key name) | | env | EnvVar[]? | Environment variables to configure after install |

OsCommands

Per-OS install commands. Supported targets: macos, linux-apt, linux-dnf, linux-pacman, windows.

• Use specific OS keys for platform-specific commands
• Use "all" for commands identical across all platforms
• Per-OS keys override "all" when both are present
• Set an OS key to false to mark explicitly unavailable

Template Variables

Available in os commands and check.command:

| Variable | Example | Description | |----------|---------|-------------| | {{name}} | node | Dependency key name | | {{version}} | 22.12.0 | Full version string | | {{major}} | 22 | Major version number | | {{arch}} | arm64 / amd64 | CPU architecture (auto-detected) |

EnvVar

| Field | Type | Description | |-------|------|-------------| | key | string | Environment variable name | | value | string? | Static value | | appendToPath | boolean? | If true, appends to PATH | | detect | string[]? | Auto-detect from these paths (first existing wins) | | fallback | string? | Fallback if detect finds nothing |

Library API

import {
  defineConfig,
  interpolate,
  resolveOsCommand,
  resolveCheckCommand,
  detectOs,
  commandExists,
} from "@scriptgun/crossdeps"

OS Detection

Auto-detects: macos, linux-apt, linux-dnf, linux-pacman, windows.

Linux distro detection uses package manager availability (apt-get, dnf, pacman).

License

MIT