Node.js (Linux ARM64 Binary)

Common errors

• Error [ERR_REQUIRE_ESM]: Must use import to load ES Module

  cause A CommonJS `require()` call was used to load a module that is defined as an ES Module.
  fix Change the `require()` call to a dynamic `import()` statement, or ensure the imported module is a CommonJS module. Check `package.json` `"type"` field and file extensions (`.mjs`/`.cjs`).

• Error: Cannot find module 'your-package-name'

  cause The specified module is either not installed, misspelled, or Node.js cannot resolve its path.
  fix Verify the module name is correct. Install the module using `npm install your-package-name` or `yarn add your-package-name`. Ensure `node_modules` is present and accessible in the project root.

• Error: listen EADDRINUSE: address already in use :::3000

  cause The network port (e.g., 3000) that the Node.js application is trying to bind to is already in use by another process.
  fix Change the application to listen on a different port, or identify and terminate the process currently occupying the port (e.g., `lsof -i :3000` on Linux/macOS or `netstat -ano | findstr :3000` on Windows, then `kill <PID>`).

• (node:12345) UnhandledPromiseRejectionWarning: Unhandled promise rejection.

  cause A Promise within the application was rejected, but there was no `.catch()` handler or `try/catch` block to explicitly handle the rejection.
  fix Add `.catch()` handlers to all promise chains or wrap `await` calls in `try/catch` blocks. For global fallbacks, implement `process.on('unhandledRejection', handler)`.

• ReferenceError: window is not defined

  cause Node.js code attempted to access the browser-specific `window` object, which does not exist in the Node.js runtime environment.
  fix Refactor the code to avoid browser-specific globals when running in Node.js. Use conditional checks (`typeof window !== 'undefined'`) or abstract browser-dependent logic into client-side-only modules.

Warnings

• breaking Node.js introduces new major versions every six months (April and October), which frequently include breaking changes. Developers must consult official release notes and migration guides (e.g., nodejs.org/docs/latest/api/changelog.html) before upgrading between major versions to ensure application compatibility.
  Fix: Always review the official Node.js changelog for your target version and follow recommended migration steps. Use a robust CI/CD pipeline with thorough testing against new Node.js versions.
• gotcha Node.js supports two module systems: CommonJS (`require`/`module.exports`) and ES Modules (`import`/`export`). Mixing them improperly or using the wrong syntax for a given module context (e.g., requiring an ESM module in a CJS file) leads to `ERR_REQUIRE_ESM` errors.
  Fix: Be consistent with module systems. Use `.mjs` for ESM and `.cjs` for CommonJS, or configure the `"type"` field in `package.json` to `'module'` for ESM or `'commonjs'` for CJS. Use dynamic `import()` for loading ESM from CJS, and `createRequire` for loading CJS from ESM.
• gotcha Unhandled Promise rejections, where a Promise rejects without a `.catch()` handler or `try/catch` block for `await` expressions, can lead to silent failures or unexpected process termination (especially since Node.js 15+).
  Fix: Ensure all Promises have `.catch()` handlers, use `try/catch` with `async/await`, or implement a global `process.on('unhandledRejection', handler)` as a last resort fallback for logging and graceful shutdown.
• gotcha Environment variables accessed via `process.env` are always strings. Attempting to use them directly as numbers or booleans will result in incorrect logic or runtime errors if explicit type conversion is not performed.
  Fix: Explicitly parse environment variables to their intended types, e.g., `parseInt(process.env.PORT || '3000', 10)` for numbers or `process.env.DEBUG === 'true'` for booleans.
• gotcha Node.js (and this specific binary package) is a server-side JavaScript runtime. Attempting to use browser-specific global objects or APIs like `window`, `document`, or `localStorage` will result in `ReferenceError: window is not defined` errors.
  Fix: Ensure that code relying on browser APIs is only executed in a browser environment. Use conditional logic (`typeof window !== 'undefined'`) or isomorphic libraries that abstract environment differences if code needs to run in both contexts.

Install

• npm install node-linux-arm64 npm
• yarn add node-linux-arm64 yarn
• pnpm add node-linux-arm64 pnpm

Imports

• readFile (from Node.js `fs` module)
  wrong:

  const { readFile } = require('fs').promises;

  correct:

  import { readFile } from 'node:fs/promises';

  For asynchronous file operations using Promises, import from `node:fs/promises`. Direct CommonJS `require()` is also common for `fs` and other built-in modules in older projects or CJS contexts.
• createServer (from Node.js `http` module)
  wrong:

  import http from 'http'; http.createServer(...);

  correct:

  import { createServer } from 'node:http';

  Named imports are often preferred for specific functions from built-in modules for better tree-shaking potential and clarity. The `node:` protocol prefix is recommended for built-in modules in ESM contexts.
• process.env (Node.js global object)
  wrong:

  import { env } from 'node:process';

  correct:

  const port = process.env.PORT ?? 3000;

  `process` is a global object in Node.js and does not require explicit `import` or `require()` for runtime access to properties like `env`, `argv`, or `exit`. Type imports are distinct.

Quickstart

Demonstrates a basic Node.js HTTP server listening on a configurable port (defaults to 3000), responding with a simple text message.

import { createServer } from 'node:http';

const hostname = '127.0.0.1';
const port = parseInt(process.env.PORT ?? '3000', 10);

const server = createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello, Node.js on Linux ARM64!\n');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});