Node.js Runtime (macOS x64 Binary)

Common errors

• sh: node: command not found

  cause The system's PATH environment variable does not include the `node_modules/.bin` directory, or you are not using a tool like `npx` that resolves local binaries.
  fix Execute your script using `npx node your-script.js` or specify the full path to the bundled Node.js executable: `node_modules/.bin/node your-script.js`.

• Error: Cannot find module 'some-module'

  cause A required module (either built-in or third-party) cannot be found by the Node.js runtime. This could be due to a missing `npm install` for third-party modules or a typo in a built-in module name.
  fix For third-party modules, ensure `npm install some-module` has been run. For built-in modules, verify the correct module name and use the `node:` prefix (e.g., `node:fs`). If using ESM, check `package.json` for `"type": "module"` and correct import paths.

Warnings

• breaking Node.js major versions, released every April and October, frequently introduce breaking changes. Projects relying on a specific Node.js version provided by this package should be prepared for potential incompatibilities when upgrading to a new major version.
  Fix: Review the official Node.js release notes and migration guides for each new major version. Pin your project to a specific `node-darwin-x64` version to control the Node.js runtime until you are ready to upgrade and adapt your code.
• gotcha This package provides a `node` executable in `node_modules/.bin`. If a system-wide Node.js installation is also present, or if your PATH is configured differently, you might inadvertently use the wrong Node.js version. This can lead to inconsistent behavior or build failures.
  Fix: Always use `npx node <script.js>` to ensure the Node.js version bundled with the package is used, or explicitly call the executable at `$(npm bin)/node <script.js>` or `node_modules/.bin/node <script.js>`.
• gotcha This package is a binary distribution and does not export any JavaScript modules directly. Attempts to `import` or `require` symbols directly from `'node-darwin-x64'` will result in errors.
  Fix: Understand that `node-darwin-x64` provides the Node.js *runtime executable*. To use Node.js features, you `import` or `require` built-in Node.js modules (e.g., `node:fs`, `node:http`) or third-party npm packages within the context of a script executed by the bundled Node.js.
• gotcha As a binary distribution, this package downloads pre-compiled Node.js executables. This introduces a supply chain dependency on the integrity of the original Node.js binaries and the `aredridel/node-bin-gen` repository.
  Fix: Ensure your project's security practices include auditing third-party binary dependencies. Verify checksums if possible, or restrict usage to trusted CI/CD environments.

Install

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

Imports

• fs
  wrong:

  import fs from 'fs';

  correct:

  import fs from 'node:fs';

  This package provides the Node.js runtime environment. These are standard Node.js built-in module imports used *within* the provided runtime, not directly exported by `node-darwin-x64` itself. Use the `node:` protocol for clarity and future-proofing in ESM contexts.
• http
  wrong:

  const http = require('http');

  correct:

  import { createServer } from 'node:http';

  This package provides the Node.js runtime environment. These are standard Node.js built-in module imports used *within* the provided runtime, not directly exported by `node-darwin-x64` itself. While `require()` is valid in CommonJS, `import` with the `node:` protocol is preferred for modern ESM.
• process
  wrong:

  import { arch } from 'process';

  correct:

  import process from 'node:process';

  `process` is a global object in Node.js, often accessed directly without explicit import. However, for explicit declaration in ESM, `import process from 'node:process';` is the correct pattern. This package provides the Node.js runtime that makes `process` available.

Quickstart

This quickstart demonstrates how to execute a Node.js script using the specific `node` executable provided by the `node-darwin-x64` package, leveraging `npx` or direct path access.

import { execSync } from 'node:child_process';
import { writeFileSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';

// Create a simple script to demonstrate running Node.js
const scriptContent = `
  console.log('Hello from Node.js (v' + process.version + ') provided by node-darwin-x64!');
  console.log('Current architecture:', process.arch);
  console.log('Current platform:', process.platform);
  console.log('Environment variable GREETING:', process.env.GREETING ?? 'not set');
`;

const scriptFilePath = join(process.cwd(), 'hello-node.js');
writeFileSync(scriptFilePath, scriptContent);

console.log('Executing script using the Node.js runtime bundled by node-darwin-x64...');

try {
  // Option 1: Using 'npx' (recommended for convenience)
  // 'npx' automatically finds executables installed in node_modules/.bin
  console.log('\n--- Running via npx ---');
  const outputNpx = execSync('npx node hello-node.js', {
    env: { ...process.env, GREETING: 'Hello from npx' },
    encoding: 'utf8', 
    stdio: 'pipe' // Capture output
  });
  console.log(outputNpx);

  // Option 2: Directly referencing the binary path
  // Useful for explicit control or when 'npx' is not available
  const nodeBinaryPath = join(process.cwd(), 'node_modules', '.bin', 'node');
  console.log(`\n--- Running directly from ${nodeBinaryPath} ---`);
  const outputDirect = execSync(`${nodeBinaryPath} hello-node.js`, {
    env: { ...process.env, GREETING: 'Hello directly' },
    encoding: 'utf8', 
    stdio: 'pipe' // Capture output
  });
  console.log(outputDirect);

} catch (error) {
  console.error('Error running script:', error.message);
  if (error.stderr) console.error('Stderr:', error.stderr);
} finally {
  unlinkSync(scriptFilePath); // Clean up the temporary script
  console.log('\nCleaned up temporary script: hello-node.js');
}