doc,test: add documentation and test on how to use addons in SEA

[joyeecheung]

Fixes: #60611

[nodejs-github-bot]

Review requested:

• @nodejs/gyp
• @nodejs/single-executable

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.55%. Comparing base (d137969) to head (9a73fa3).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #59582      +/-   ##
==========================================
+ Coverage   88.53%   88.55%   +0.01%     
==========================================
  Files         703      703              
  Lines      208077   208077              
  Branches    40083    40086       +3     
==========================================
+ Hits       184214   184253      +39     
+ Misses      15881    15850      -31     
+ Partials     7982     7974       -8     

see 44 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[joyeecheung]

Formatted the addon code and changed the test to use cwd: tmpdir.path for the SEA since the testing environment does not allow access to os.tmpdir().

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/68861/

[joyeecheung]

Forgot the skipIfSingleExecutableIsNotSupported() call, added.

[joyeecheung]

Forgot to skip on ppc64le like what's done in #59563, added

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/68875/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/68888/

[joyeecheung]

For some reason, this doesn't actually work on Linux arm64 - but only in the GitHub actions, and x64 Linux seems to work alright in GitHub actions, and in the Jenkins CI, both work alright.

[process 202296]: --- stderr ---
/home/runner/work/node/node/node/test/.tmp.4536/sea: symbol lookup error: /home/runner/work/node/node/node/test/.tmp.4536/hello.node: undefined symbol: napi_define_properties

[process 202296]: --- stdout ---

[process 202296]: status = 127, signal = null
/home/runner/work/node/node/node/test/common/child_process.js:98
    throw error;
    ^

Error: - process terminated with status 127, expected 0

[joyeecheung]

I poked at it a bit and it looks like the failure in the github actions on linux arm64 is a legit bug of postject - which only reproduces in a Linux arm64 container, but not on bare metal, or Linux x64. Opened nodejs/postject#105

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/70114/

[killghost]

Requirements for Using an Addon Plugin:

1. Webpack Configuration (webpack.config.js):

module.exports = {
  // Prevent bundling the .node addon
  externals: {
    "aaa.node": "commonjs aaa.node"
  },
  // Other configurations (entry, output, etc.) remain unchanged
};

#####2. TypeScript Script (your-script.ts):

// Ensure the path is correct (e.g., relative to the runtime directory)
const module = require("./path/to/aaa.node"); // Adjust the path as needed

######3.Webpack Build Command:
npx tsc && npx webpack --mode production

######4.Exclude aaa.node from the final executable (e.g., a bundled .exe file):
The addon should not be embedded into the final bundled file (e.g., via tools like pkg or webpack).
At runtime, require("aaa.node") must locate the file via its filesystem path (not from the bundled package).


Thanks