Best practice for Node SEA with ESM-only CLI, Workers, and native addons

[Niladri2003]

Node.js Version

v24.11.1

NPM Version

11.6.2

Operating System

Ubuntu

Subsystem

Other

Description

I’m looking for guidance around Single Executable Applications (SEA) when combining ESM-only code, Worker threads, and native addons.

Background

I’m developing a production CLI tool using:

• TypeScript
• ESM-only codebase ("type": "module")
• Node.js Worker threads
• Several ESM-only dependencies (ink, chalk@5, yoga-layout, etc.)
• A custom npm package with native addons (.node), also maintained by me and published using node-pre-gyp with prebuilt binaries per platform

The CLI and the native-addon package both work correctly when run via a normal Node.js installation.

What I tried with SEA

• Built a CJS output of the CLI (using tsup / tsc)
• Used Node.js v20.11.x consistently to:
  - generate the SEA blob (--experimental-sea-config)
  - inject it into a Node binary using postject
• Pointed sea-config.json to the CJS entry (dist/index.cjs)

This works upto a point The sea binary starts
but then i am getting error that my addon package is not found and require is not working for loading chalk and others.

node:internal/util/embedding:48
    throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
    ^

Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: @pinggy/pinggy
    at embedderRequire (node:internal/util/embedding:48:11)
    at dist_sea/index.cjs:833:22
    at embedderRunCjs (node:internal/util/embedding:37:10)
    at node:internal/main/embedding:18:8 {
  code: 'ERR_UNKNOWN_BUILTIN_MODULE'
}

Node.js v20.11.1

Core questions

1. Is SEA expected to support loading native addons from node_modules at runtime?
2. Is there any official or recommended way for esm-first CLI using SEA( especially with Workers) ?

Any guidance or confirmation from the Node.js team would be greatly appreciated.

Minimal Reproduction

No response

Output

No response

Before You Submit

• I have looked for issues that already exist before submitting this
• My issue follows the guidelines in the README file, and follows the 'How to ask a good question' guide at https://stackoverflow.com/help/how-to-ask

[Ranjithh44]

Why this happens

When running inside a SEA binary, Node does not perform normal filesystem-based module resolution. In particular:

require() / import() do not search node_modules

Only the following modules are resolvable at runtime:

Built-in Node modules

Code embedded in the SEA snapshot

Modules explicitly loaded via absolute paths

Because of this, any statement like:

require("@pinggy/pinggy")

is interpreted by the SEA embedder as a request for a built-in module, which results in:

ERR_UNKNOWN_BUILTIN_MODULE

This applies equally to:

Regular JS dependencies (e.g. chalk, ink)

ESM-only packages

Native addons (.node) distributed via node-pre-gyp

Native addons and SEA

SEA does not currently support loading native addons from node_modules at runtime.
Prebuilt binaries managed by node-pre-gyp are not discovered or resolved automatically inside SEA.

If native addons are required, they must be treated as external assets and loaded explicitly via absolute paths on disk. SEA does not bundle or resolve native addons for you.

ESM, Workers, and SEA

SEA is currently optimized for CJS-first execution. While ESM can work in limited scenarios, the following combinations are not fully supported today:

ESM-only CLIs

Worker threads with ESM loaders

Dynamic imports combined with SEA snapshots

Runtime dependency resolution inside workers

Worker threads require explicit entry points and do not inherit the same module resolution context as a normal Node process when running under SEA

[parsapy1391-lang]

parsa

[parsapy1391-lang]

let x = 2;