bin-links: Package Binary Linker

Common errors

• Error: EACCES: permission denied, link '...' -> '...'

  cause The Node.js process lacks the necessary file system permissions to create symbolic links or shims in the target directory.
  fix Ensure the user running the Node.js process has write permissions to the destination directory (e.g., `node_modules/.bin` or global `bin` directory). On Unix-like systems, you might need to use `sudo` for global installations, though this is generally discouraged for local `npm install`.

• TypeError: require is not a function

  cause Attempting to use `require('bin-links')` in an ES Module context where CommonJS `require` is not natively available or polyfilled.
  fix Refactor your import statement to use `import binLinks from 'bin-links';` to align with ESM syntax. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• Error: The 'engines' field is not compatible with the current Node.js version.

  cause The `bin-links` package specifies a strict Node.js engine range in its `package.json`, and your current Node.js version falls outside this range.
  fix Upgrade your Node.js runtime to a version that satisfies the `engines.node` requirement specified in `bin-links`'s `package.json` (e.g., `^20.17.0 || >=22.9.0` for v6.0.0). Use a Node Version Manager (NVM) to switch to a compatible version.

Warnings

• breaking Node.js engine requirements have been progressively tightened. Version 6.0.0 requires Node.js `^20.17.0 || >=22.9.0`. Ensure your Node.js environment meets these specifications to avoid compatibility issues.
  Fix: Upgrade your Node.js runtime to a compatible version (e.g., Node.js 20.17.0+ or 22.9.0+). Use nvm or your system's package manager to manage Node.js versions.
• breaking With the release of v5.0.0, the Node.js engine requirement was updated to `^18.17.0 || >=20.5.0`. Running on older Node.js versions will lead to failures.
  Fix: Upgrade your Node.js runtime to version 18.17.0+ or 20.5.0+.
• breaking Version 4.0.0 introduced a significant change where `bin-links` no longer automatically attempts to change file ownership. Operations that previously relied on this automatic ownership alteration may now require manual handling of file permissions.
  Fix: Review your installation scripts and environment. If file ownership changes are critical for your setup (e.g., for specific user permissions), implement explicit `chown` or similar commands after `binLinks` execution, or ensure appropriate permissions are set beforehand.
• gotcha On Windows, `bin-links` creates `.cmd` and `.ps1` shims in addition to the binary itself. Directly invoking the raw `.js` binary file or relying on Unix-style symbolic link behavior might not work as expected in standard Windows command prompts.
  Fix: Always invoke the binary by its name (e.g., `my-cli` not `my-cli.js`) to allow the shell to correctly pick up the generated shim. Ensure your `PATH` includes the `node_modules/.bin` directory.
• gotcha For global package installations, `bin-links` (via npm's internal logic) will only overwrite existing binaries if they were previously installed by the *same* package. This is a security measure to prevent arbitrary file overwrites. Using `force: true` might not bypass this specific safety check for global installs in all npm versions.
  Fix: If you encounter issues with global binary overwrites, consider explicitly uninstalling the old package version first, or investigate if the conflicting binary truly belongs to a different package. Avoid relying on `force: true` to override existing binaries from unrelated packages in global contexts.

Install

• npm install bin-links npm
• yarn add bin-links yarn
• pnpm add bin-links pnpm

Imports

• binLinks
  wrong:

  const binLinks = require('bin-links');

  correct:

  import binLinks from 'bin-links';

  While primarily a CommonJS module, it's designed to be imported as a default export in ES Modules. Using 'require' in an ESM context will throw a 'require is not defined' error.
• binLinks.getPaths
  wrong:

  import { getPaths } from 'bin-links';

  correct:

  import binLinks from 'bin-links';
  const paths = await binLinks.getPaths({ /* ... */ });

  'getPaths' is a method directly attached to the default 'binLinks' function/object, not a separate named export. Attempting a named import will result in 'getPaths is not exported from bin-links'.
• binLinks.checkBins
  wrong:

  import { checkBins } from 'bin-links';

  correct:

  import binLinks from 'bin-links';
  await binLinks.checkBins({ /* ... */ });

  'checkBins' is a method directly attached to the default 'binLinks' function/object, not a separate named export. Attempting a named import will result in 'checkBins is not exported from bin-links'.

Quickstart

This quickstart demonstrates how to use `bin-links` to create symbolic links for a package's binaries and man pages, simulating a local package installation. It shows the core `binLinks` function, along with `getPaths` and `checkBins` utility methods. The example includes directory setup and cleanup.

const binLinks = require('bin-links');
const path = require('path');
const fs = require('fs/promises');

// Simulate a package.json read for demonstration
async function readPackageJson(packagePath) {
  try {
    const pkgContent = await fs.readFile(packagePath, 'utf8');
    return JSON.parse(pkgContent);
  } catch (err) {
    // Create a dummy package.json content if file not found
    return {
      name: 'some-package',
      version: '1.0.0',
      bin: {
        'my-cli': 'cli.js'
      },
      man: [
        'man/my-cli.1'
      ]
    };
  }
}

async function runBinLinkingExample() {
  // Define paths relative to the current script execution
  const tempDir = path.join(__dirname, 'temp-link-test');
  const packageDir = path.join(tempDir, 'node_modules', 'some-package');
  const binDir = path.join(tempDir, 'node_modules', '.bin');
  const manDir = path.join(tempDir, 'share', 'man');

  // Ensure necessary directories exist
  await fs.mkdir(packageDir, { recursive: true });
  await fs.mkdir(binDir, { recursive: true });
  await fs.mkdir(path.join(packageDir, 'man'), { recursive: true });
  await fs.mkdir(manDir, { recursive: true });

  // Create dummy executable and man page files
  await fs.writeFile(path.join(packageDir, 'cli.js'), '#!/usr/bin/env node\nconsole.log("Hello from my-cli!");', { mode: 0o755 });
  await fs.writeFile(path.join(packageDir, 'man', 'my-cli.1'), '.TH "MY-CLI" "1" "2025-01-01" "1.0.0" "My CLI Manual"\n.SH NAME\nmy-cli - A sample command-line interface', { recursive: true });

  const pkg = await readPackageJson(path.join(packageDir, 'package.json'));

  console.log('Attempting to link binaries and man pages for ' + pkg.name + '...');
  try {
    await binLinks({
      path: packageDir,
      pkg: pkg,
      global: false, // Set to true for global install simulation
      top: true,     // This is the top-level package being linked
      force: true    // Overwrite existing links if any
    });
    console.log('Binaries and man pages linked successfully!');

    // Demonstrate checking for conflicts (should pass with force: true)
    await binLinks.checkBins({
      path: packageDir,
      pkg: pkg,
      global: false,
      top: true,
      force: true
    });
    console.log('No conflicting bins found (or forced overwrite).');

    // List potential link paths (does not touch filesystem)
    const potentialPaths = binLinks.getPaths({
      path: packageDir,
      pkg: pkg,
      global: false,
      top: true
    });
    console.log('Potential link paths:', potentialPaths);

  } catch (error) {
    console.error('Error during binary linking example:', error.message);
  } finally {
    // Clean up temporary directory after example
    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
    console.log('Cleanup complete.');
  }
}

runBinLinkingExample();