Overview

Configures pkg to build Node.js binaries, bundling assets and targeting multiple platforms. It defines a structured pkg config with scripts, assets, targets, and an outputPath, plus a binary build script to output gzip-compressed executables. This enables cross-platform distribution from a single repo.

How This Skill Works

The skill specifies a pkg configuration block that maps runtime files to pkg's scripts and assets, designates cross-platform targets (e.g., node18-linux-x64, node18-macos-x64, node18-win-x64), and sets an outputPath for binaries. It also provides an npm script, build:binary, that runs pkg . --compress GZip to generate the executables for all targets.

When to Use It

• You need to ship a Node.js app as cross-platform binaries (Linux, macOS, Windows) from a single repository.
• Your app bundles assets (JSON, data files) and specific runtime modules (e.g., better-sqlite3) that must be included in the binary.
• You want a dedicated npm script (build:binary) to automate the binary packaging process.
• You publish or distribute artifacts through CLI distribution or package publishing workflows and need consistent binaries.
• You want to lock the output structure (dist/js scripts, assets, and built binaries) using a defined outputPath like 'build'.

Quick Start

1. Step 1: Add a pkg config block in your project that mirrors the generated patterns (scripts, assets, targets, outputPath).
2. Step 2: Add a build script: "build:binary": "pkg . --compress GZip" to your package.json.
3. Step 3: Run npm run build:binary and verify the binaries appear under build/ for all targets.

Best Practices

• Align the assets array with runtime needs (e.g., dist/**/*.json, node_modules/... to ensure all required files are included).
• Pin the target Node.js versions and platforms you actually support (node18-linux-x64, node18-macos-x64, node18-win-x64).
• Use a dedicated outputPath to keep binaries separate from source and build artifacts.
• Include essential native modules (e.g., better-sqlite3) to prevent runtime missing assets in the binary.
• Validate binaries on all target platforms in CI to catch platform-specific issues early.

Example Use Cases

• Build Linux x64, macOS x64, and Windows x64 binaries from a single repo using the provided patterns and npm script build:binary.
• Bundle dist/**/*.js as scripts and include dist/**/*.json plus node_modules/better-sqlite3/**/* as assets for the final binary.
• Publish the outputs under the build/ directory after running npm run build:binary, enabling CI-driven release pipelines.
• Use the exact targets node18-linux-x64, node18-macos-x64, node18-win-x64 to ensure compatibility with modern Node runtimes.
• Maintain a clean separation between source (src, dist) and binaries by preserving the outputPath in the config.

Frequently Asked Questions