Node.js (Linux x64 Distribution)

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax within an ES Module file or project configured as ESM.
  fix Refactor `require()` calls to `import` statements. If a module strictly needs `require()`, ensure the file is treated as CommonJS (e.g., `.cjs` extension or no `"type": "module"` in `package.json`).

• Error: Cannot find module 'some-package'

  cause The module specified in `import` or `require` does not exist, is not correctly installed, or its path is incorrect.
  fix Verify the package name, ensure it's installed via `npm install some-package`, and check the import/require path. For local files, ensure the path includes `./` or `../` prefixes and the correct extension.

• SyntaxError: Unexpected token 'export'

  cause Attempting to use ES Module `export` syntax in a CommonJS module file or project not configured for ESM.
  fix Either convert the file/project to ESM (e.g., add `"type": "module"` to `package.json` or use `.mjs` extension) or refactor `export` statements to CommonJS `module.exports = ...` or `exports.name = ...`.

Warnings

• breaking Node.js introduces breaking changes with each new major 'Current' version, released approximately every six months (April and October). Projects should carefully review migration guides before upgrading across major versions. For instance, Node.js 24 introduced OpenSSL 3.5, restricting short RSA/DSA/DH keys and RC4 cipher suites, and had stricter validation for `fetch()` and `AbortSignal`.
  Fix: Always consult the official Node.js release notes and migration guides (e.g., nodejs.org/en/docs/guides/nodejs-release-post-mortem) when upgrading between major versions, especially from LTS to a newer Current or LTS release. Prioritize LTS versions for production for stability.
• gotcha The Node.js module system has fundamental differences between CommonJS (CJS) and ES Modules (ESM). Attempting to use `require()` in an ES module or `import` in a CommonJS module without proper configuration (like `"type": "module"` in `package.json` or `.mjs` extensions) will lead to runtime errors like `ReferenceError: require is not defined` or `SyntaxError: Unexpected token 'export'`.
  Fix: Explicitly define module type in `package.json` with `"type": "module"` for ESM, or stick to `.mjs` for ESM and `.cjs` for CJS. Convert `require` calls to `import` statements and vice-versa as appropriate for the module context. Be aware of differences in `__dirname` and `__filename` availability in ESM.
• gotcha For production applications, it is strongly recommended to use Long Term Support (LTS) releases of Node.js over 'Current' releases. Current releases are under active development and have a shorter support window (8 months for October releases) compared to LTS versions (30 months total support including active and maintenance phases). LTS versions focus on stability and security, making them more suitable for critical deployments.
  Fix: Develop against the latest 'Current' release for new features, but deploy and maintain production applications on 'Active LTS' release lines. Plan regular upgrades between LTS versions to stay current with security patches and improvements.

Install

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

Imports

• readFile (from 'fs/promises')
  wrong:

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

  correct:

  import { readFile } from 'fs/promises';

  Modern Node.js development often uses the promises-based API for built-in modules with ESM syntax. The CommonJS `require` for `fs/promises` is incorrect.
• http (default from 'http')
  wrong:

  import http from 'http';

  correct:

  import * as http from 'http';

  While CommonJS modules allow `const http = require('http');`, ESM imports for Node.js built-in modules typically require `* as` for the entire module, as they don't have a default export.
• join (from 'path')
  wrong:

  const path = require('path'); const joinedPath = path.join(...);

  correct:

  import { join } from 'path';

  Named imports are generally preferred in ESM for clarity and tree-shaking. The CommonJS pattern `require('path')` then accessing `.join` is also valid in CJS environments.

Quickstart

This quickstart demonstrates a basic HTTP server in Node.js, handling root and `/readfile` routes. It showcases ESM syntax for importing built-in modules (http, fs/promises, path, url) and performing asynchronous file operations. It runs an HTTP server and reads a local file.

import * as http from 'http';
import { readFile } from 'fs/promises';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const hostname = '127.0.0.1';
const port = 3000;

// __dirname equivalent for ESM
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const server = http.createServer(async (req, res) => {
  res.setHeader('Content-Type', 'text/plain');
  if (req.url === '/') {
    res.statusCode = 200;
    res.end('Hello Node.js World!\n');
  } else if (req.url === '/readfile') {
    try {
      // Assuming a 'sample.txt' file exists in the same directory
      const filePath = join(__dirname, 'sample.txt');
      const content = await readFile(filePath, 'utf8');
      res.statusCode = 200;
      res.end(`File content:\n${content}\n`);
    } catch (error) {
      res.statusCode = 500;
      res.end('Error reading file. Ensure "sample.txt" exists.\n');
    }
  } else {
    res.statusCode = 404;
    res.end('Not Found\n');
  }
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
  console.log(`Visit http://${hostname}:${port}/readfile (requires a 'sample.txt' file)`);
  console.log(`To create 'sample.txt': echo "Hello from sample.txt" > sample.txt`);
});