Nodepile

Compile your Node.js applications into standalone executable files.

Nodepile bundles your JavaScript code, all dependencies, and the Node.js runtime into a single .exe file. Your users can run your app without installing Node.js or any dependencies just double click and go.

Table of Contents

• What is Nodepile?
• Installation
• Quick Start
• CLI Commands
  • build
  • init
• Configuration
• Target Platforms
• Programmatic Usage
• How It Works
• Troubleshooting
• License

What is Nodepile?

When you build a desktop app, CLI tool, or utility with Node.js, sharing it usually means:

1. Asking users to install Node.js
2. Having them run npm install
3. Hoping their system matches your setup

Nodepile solves this by packaging everything your app needs into one executable. Think of it as shipping your app with Node.js built-in.

Good use cases:

• Desktop applications with Electron or similar
• CLI tools you want to distribute easily
• Internal utilities for non-technical teammates
• Kiosk apps or embedded systems

Not ideal for:

• Web servers (just deploy normally)
• Apps that need frequent updates (users need to redownload)
• Very small scripts (overkill for a few lines)

Installation

Install globally to use the nodepile command anywhere:

npm install -g nodepile

Or add to a specific project:

npm install --save-dev nodepile

Quick Start

1. Create a config file

nodepile init

This generates nodepile.config.js with default settings.

2. Build your executable

nodepile build src/index.js

3. Find your .exe

Check the ./dist folder. Share it with anyone—they can run it without Node.js installed.

CLI Commands

build

Compile your app into an executable.

nodepile build src/index.js

What it does: Takes your entry point (file or directory) and bundles it with the Node.js runtime into a standalone .exe file.

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --output | -o | Output directory | ./dist | | --name | -n | Executable name | From package.json | | --targets | -t | Platforms to build for | node18-win-x64 | | --config | -c | Config file path | nodepile.config.js | | --no-config | — | Skip config file | — | | --debug | -d | Show debug output | false |

Examples:

# Custom output folder
nodepile build src/index.js -o ./build

# Name the executable
nodepile build src/index.js -n my-tool

# Build for Windows and Linux
nodepile build src/index.js -t "node18-win-x64,node18-linux-x64"

# Skip config file entirely
nodepile build src/index.js --no-config

# Build entire project from current directory (auto-detects entry point)
nodepile build .

# Build from a directory
nodepile build ./my-project -n my-app

init

Create a starter nodepile.config.js file.

nodepile init

What it does: Generates a nodepile.config.js file in your current directory with default settings for entry point, output directory, targets, and build options.

Configuration

Create a nodepile.config.js in your project root:

module.exports = {
  entry: 'src/index.js',
  output: './dist',
  name: 'my-app',
  targets: ['node18-win-x64', 'node18-linux-x64'],
  assets: ['public/**/*', 'config/*.json'],
  pkg: {
    scripts: 'dist/**/*.js',
    assets: ['node_modules/some-module/**/*']
  },
  options: {
    compress: true,
    encrypt: false
  }
};

Options Reference

| Option | Type | Description | |--------|------|-------------| | entry | string | Your app's main file | | output | string | Build output folder | | name | string | Executable filename (optional) | | targets | array | Platforms to build for | | assets | array | Extra files to bundle (glob patterns) | | pkg | object | Advanced pkg configuration | | options.compress | boolean | Compress bytecode to reduce size | | options.encrypt | boolean | Encrypt bytecode for protection |

When to Use assets

If your app reads external files (configs, templates, static assets), list them here:

assets: [
  'public/**/*',
  'templates/**/*.html',
  'data/*.json'
]

This ensures they're bundled or copied alongside your executable.

Target Platforms

Build for any combination of these:

Windows

• node14-win-x64
• node16-win-x64
• node18-win-x64
• node20-win-x64

Linux

• node14-linux-x64
• node16-linux-x64
• node18-linux-x64
• node20-linux-x64

macOS

• node14-macos-x64
• node16-macos-x64
• node18-macos-x64
• node20-macos-x64

Build for multiple platforms:

nodepile build src/index.js -t "node18-win-x64,node18-linux-x64,node18-macos-x64"

Note: You can build for any platform from any OS, but native modules may need platform-specific builds.

Programmatic Usage

Use Nodepile in your own scripts or build pipelines:

const { compile } = require('nodepile');

async function build() {
  await compile({
    entry: 'src/index.js',
    output: './build',
    name: 'my-app',
    targets: ['node18-win-x64'],
    assets: ['public/**/*'],
    options: {
      compress: true
    }
  });

  console.log('Build complete!');
}

build();

API

compile(options)

Returns a Promise that resolves with build info.

| Option | Type | Description | |--------|------|-------------| | entry | string | Entry point file | | output | string | Output directory | | name | string | Executable name | | targets | array | Target platforms | | assets | array | Additional files | | pkg | object | pkg config overrides | | options | object | Build options | | configPath | string|null | Config file path (or null to skip) |

How It Works

Nodepile wraps pkg, which handles the actual compilation:

1. Parse - Scans your entry file and all require() statements
2. Bundle - Collects your code and dependencies
3. Embed - Packages everything with a Node.js runtime
4. Compile - Outputs a standalone executable

The result is a self-contained binary that extracts and runs your code in a temporary environment.

Output Size

Expect executables around 35-50 MB (the Node.js runtime is ~30 MB). Enable compression to reduce this:

options: { compress: true }

Troubleshooting

"Module not found" at runtime

Some dynamic requires can't be detected at build time. Add the module to your config:

pkg: {
  assets: ['node_modules/problematic-module/**/*']
}

Executable is too large

• Enable compression: options: { compress: true }
• Remove unused dependencies
• Consider if all features are needed

Native modules not working

Native modules (like sqlite3, bcrypt) are compiled for specific platforms. Options:

1. Build on each target platform
2. Use pure JavaScript alternatives
3. Pre-compile native modules for each target

Config file not loading

Make sure nodepile.config.js is in your project root, or specify the path:

nodepile build src/index.js -c ./config/nodepile.config.js

License

MIT

Repository: https://github.com/qbiradev/nodepile

Built with pkg by Vercel.