Home

Node Package Builder

npm version
License: MIT
Node.js Version
Downloads
GitHub Stars
GitHub Issues

A powerful cross-platform npm module for building Node.js applications into single executable files using Node.js Single Executable Applications (SEA) feature.

Installation โ€ข Quick Start โ€ข Documentation โ€ข Examples โ€ข Contributing

Features

  • ๐Ÿš€ Build single executable applications from Node.js projects
  • ๐ŸŒ True cross-platform support - Build for Linux, macOS, and Windows from any platform
  • ๐Ÿ“ฅ Automatic Node.js downloading - Downloads compatible Node.js binaries from the internet
  • ๐Ÿ“ฆ Simple CLI interface
  • โš™๏ธ Configurable build options
  • ๐ŸŽฏ Support for assets bundling
  • ๐Ÿ”ง Code cache and snapshot optimization
  • ๐Ÿ”„ Version management - Uses Node.js versions 19.9.0+ with smart version selection

Requirements

  • Node.js >= 18.16.0 (for SEA support)
  • npm or yarn

Installation

Global Installation (Recommended)

npm install -g node-package-builder

Local Installation

npm install node-package-builder

Quick Start

1. Create a sample project

node-package-builder init my-app
cd my-app

2. Build executable for current platform

node-package-builder build

3. Run your executable

./app

CLI Usage

Build Command

node-package-builder build [options]

Options:

  • -m, --main <file>: Main JavaScript file (default: "index.js")
  • -o, --output <name>: Output executable name (default: "app")
  • -p, --platforms <platforms>: Target platforms, comma-separated (default: "linux,darwin,win32")
  • --use-snapshot: Enable snapshot support (default: false)
  • --use-code-cache: Enable code cache (default: false)
  • --assets <assets>: Assets to include as JSON string (default: "{}")
  • --disable-warning: Disable experimental SEA warning (default: true)

Examples:

# Build for current platform
node-package-builder build

# Build for multiple platforms
node-package-builder build --platforms linux,darwin,win32

# Build with custom main file and output name
node-package-builder build --main src/app.js --output myapp

# Build with assets
node-package-builder build --assets '{"config.json": "./config.json", "data.txt": "./data.txt"}'

# Build with optimizations
node-package-builder build --use-code-cache --use-snapshot

Other Commands

# List supported platforms
node-package-builder platforms

# Initialize a sample project
node-package-builder init [project-name]

# Clean up temporary build files
node-package-builder cleanup

# Show help
node-package-builder --help

Programmatic Usage

const NodePackageBuilder = require('node-package-builder');

async function buildApp() {
  const builder = new NodePackageBuilder({
    main: 'src/index.js',
    output: 'myapp',
    platforms: ['linux', 'darwin', 'win32'],
    useCodeCache: true,
    assets: {
      'config.json': './config.json'
    }
  });

  try {
    const results = await builder.build();
    console.log('Build results:', results);
  } catch (error) {
    console.error('Build failed:', error);
  }
}

buildApp();

Configuration Options

Option Type Default Description
main string 'index.js' Entry point of your application
output string 'app' Name of the output executable
platforms array ['linux', 'darwin', 'win32'] Target platforms to build for
useSnapshot boolean false Enable V8 snapshot for faster startup
useCodeCache boolean false Enable code cache for faster startup
assets object {} Additional files to bundle
disableExperimentalSEAWarning boolean true Disable experimental feature warning
tempDir string os.tmpdir()/node-package-builder Custom temporary directory for build files

Cross-Platform Building

NEW: True Cross-Platform Support! ๐ŸŽ‰

You can now build executables for any platform from any platform:

# Build for all platforms from macOS
node-package-builder build --platforms linux,darwin,win32

# Build Windows executable from Linux
node-package-builder build --platforms win32

# Build Linux executable from Windows
node-package-builder build --platforms linux

How it works:

  1. Automatic Node.js Download: Downloads compatible Node.js binaries (v19.9.0+) from nodejs.org
  2. Smart Version Selection: Prefers stable LTS versions (20.x series) for maximum compatibility
  3. Local Caching: Downloaded binaries are cached in ~/.node-package-builder/cache/
  4. Platform-Specific Optimization: Automatically adjusts build settings per platform

Platform-specific behavior:

  • Same platform: Uses your local Node.js executable
  • Different platform: Downloads and uses platform-specific Node.js binary
  • useSnapshot and useCodeCache are automatically disabled for cross-platform builds
  • Windows builds include automatic .exe extension

Version Management:

  • Minimum version: 19.9.0 (required for SEA support)
  • Preferred versions: 20.18.0, 20.17.0, 20.16.0, 20.15.1
  • Fallback version: 20.18.0 if internet is unavailable
  • Maximum version: 22.x (for stability)

Temporary File Management

NEW: Smart Temporary File Handling! ๐Ÿงน

The builder now uses a sophisticated temporary file system to prevent conflicts and ensure clean builds:

Features:

  • Isolated Build Directories: Each build gets a unique temporary directory
  • Automatic Cleanup: Temporary files are automatically cleaned after each build
  • Conflict Prevention: Multiple simultaneous builds won't interfere with each other
  • Manual Cleanup: Clean up all temporary files with the cleanup command

How it works:

  1. Unique Build IDs: Each build gets a unique ID (timestamp + random hash)
  2. Temporary Directory: Files are created in os.tmpdir()/node-package-builder/build-{id}/
  3. Automatic Cleanup: Temporary directory is removed after build completion
  4. Manual Cleanup: Use node-package-builder cleanup to remove all temporary directories

Examples:

# Build with automatic cleanup
node-package-builder build

# Manual cleanup of all temporary files
node-package-builder cleanup

# Custom temporary directory
const builder = new NodePackageBuilder({
  main: 'index.js',
  tempDir: '/custom/temp/path'
});

Programmatic Cleanup:

const { cleanupAllTempDirs } = require('node-package-builder');

// Clean up all temporary directories
cleanupAllTempDirs();

Assets Bundling

You can bundle additional files with your executable:

const builder = new NodePackageBuilder({
  main: 'index.js',
  assets: {
    'config.json': './config/production.json',
    'templates/main.html': './src/templates/main.html',
    'data.txt': './data/sample.txt'
  }
});

Access bundled assets in your application:

const fs = require('fs');
const { getAsset } = require('node:sea');

// Read bundled asset
const config = JSON.parse(getAsset('config.json', 'utf8'));
const template = getAsset('templates/main.html', 'utf8');

Platform-Specific Notes

macOS

  • Code signing is automatically handled
  • Requires Xcode command line tools for signing

Windows

  • .exe extension is automatically added
  • Optional code signing with signtool

Linux

  • No additional requirements
  • Executable permissions are set automatically

Troubleshooting

Common Issues

  1. "postject not found"

    npm install -g postject
    
  2. Permission denied on macOS/Linux

    chmod +x ./your-app
    
  3. Code signing issues on macOS

    • Install Xcode command line tools: xcode-select --install
    • Or disable signing warnings in system preferences
  4. Large executable size

    • Use --use-code-cache for better compression
    • Minimize dependencies in your application
  5. Build conflicts with multiple builds

    # Clean up temporary files
    node-package-builder cleanup
    
  6. Temporary files not cleaned up

    • Temporary files are automatically cleaned after each build
    • Use node-package-builder cleanup to manually clean all temp files
    • Check os.tmpdir()/node-package-builder/ for any remaining files

Examples

Check out the examples/ directory for sample projects:

  • Simple CLI application
  • Web server application
  • Application with bundled assets

API Documentation

For detailed API documentation with TypeScript support, see the generated JSDoc documentation:

npm run docs

The documentation will be generated in the docs/ directory.

TypeScript Support

This package includes full TypeScript definitions. You can use it in TypeScript projects:

import NodePackageBuilder from 'node-package-builder';

const builder = new NodePackageBuilder({
  main: 'src/index.ts',
  output: 'myapp',
  platforms: ['linux', 'darwin', 'win32']
});

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

  1. Fork the repository: https://github.com/sw3do/node-package-builder
  2. Clone your fork: git clone https://github.com/sw3do/node-package-builder.git
  3. Install dependencies: npm install
  4. Create your feature branch: git checkout -b feature/amazing-feature
  5. Make your changes and add tests
  6. Run type checking: npm run type-check
  7. Generate documentation: npm run docs
  8. Commit your changes: git commit -m 'Add amazing feature'
  9. Push to the branch: git push origin feature/amazing-feature
  10. Open a Pull Request

Code Style

  • Follow the existing code style
  • Add JSDoc comments for all public methods
  • Include TypeScript definitions
  • Write tests for new features

Changelog

See CHANGELOG.md for a detailed history of changes.

Support

License

MIT License - see LICENSE file for details.

Author

sw3do - GitHub

Related Projects


Made with โค๏ธ by sw3do

โญ Star this project if you find it useful!

bin/cli.js

CLI tool for building Node.js applications into single executable files

Source: