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

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