Skip to content

Latest commit

 

History

History
121 lines (86 loc) · 4.21 KB

README.md

File metadata and controls

121 lines (86 loc) · 4.21 KB

CI Quality Gate Status npm

@getlarge/nx-node-sea

A plugin for Nx that provides integration with Node.js Single Executable Applications (SEA).

Overview

This plugin helps you create Node.js Single Executable Applications (SEA) within your Nx workspace. It automates the process of generating SEA preparation blobs and creating standalone executables that bundle your Node.js application.

Requirements

  • Node.js 20 or higher (SEA feature requirement)
  • Nx 20.0.6 or higher

Installation

npm install --save-dev @getlarge/nx-node-sea

Usage

1. Create a sea-config.json file

Create a sea-config.json file in your project's root directory:

{
  "main": "dist/your-app/main.js",
  "output": "dist/your-app/main.blob",
  "disableExperimentalSEAWarning": false,
  "useSnapshot": false,
  "useCodeCache": false
}

2. Configure the plugin in nx.json

Add the plugin configuration to your nx.json file:

{
  "plugins": [
    {
      "plugin": "@getlarge/nx-node-sea",
      "options": {
        "seaTargetName": "sea-build",
        "buildTarget": "build"
      }
    }
  ]
}

Note: The buildTarget option specifies the target that will be used to build your application before creating the SEA. The default value is "build".

3. Build your SEA

nx run your-app:sea-build

This will:

  1. Build your application using the specified build target
  2. Generate a SEA preparation blob
  3. Create a standalone executable

Configuration Options

Plugin Options

Option Description Default
buildTarget The target to build your application before creating the SEA "build"
seaTargetName The name of the target that will be created to build the SEA "sea-build"

SEA Config Options

Option Description Required
main Path to the main JavaScript file of your application Yes
output Path where the SEA blob will be generated Yes
disableExperimentalSEAWarning Disable warnings about experimental feature No
useSnapshot Use V8 snapshot for faster startup No
useCodeCache Use code cache for faster startup No
assets Record of assets to include in the blob No

Platform Support

The plugin automatically handles platform-specific differences for:

  • Linux
  • macOS (includes code signing)
  • Windows

Learn More

Example Project Structure

my-app/
├── sea-config.json
├── project.json
└── src/
    └── main.ts

The plugin will create a standalone executable in the directory specified in sea-config.json (output).

On macOS and Linux, the binary will be named node. On Windows, it will be named node.exe.

You can find a complete working example in the node-sea-demo repository.