Node.js --preserve-symlinks Flag Support

1.0.0 · maintenance · verified Sun Apr 19

This package, `supports-preserve-symlinks-flag`, is a focused, lightweight utility designed to programmatically determine whether the currently executing Node.js environment supports the `--preserve-symlinks` command-line flag. Currently at version 1.0.0, this package is highly stable and is likely in a maintenance-only mode, with new releases being infrequent unless Node.js introduces significant changes to its symlink resolution mechanisms or CLI flag behavior. Its core differentiation lies in its single-purpose simplicity, providing a direct boolean value (or `null` when executed in a browser environment) indicating support, without relying on any external dependencies. This functionality is crucial for developers needing to adapt application behavior or build processes based on the specific symlink resolution capabilities of the Node.js runtime, especially when deploying across diverse environments that might include older Node.js versions (specifically those prior to v6.2) where this flag was not available. It serves as a reliable check for ensuring compatibility and correct operation of file system-dependent logic.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` directly in a pure ES module (`.mjs` file or `"type": "module"` package).

fix Use dynamic import: `const { default: supportsPreserveSymlinks } = await import('node-supports-preserve-symlinks-flag');` or convert your file to CommonJS (`.cjs` or remove `"type": "module"` from `package.json`).
```
TypeError: supportsPreserveSymlinks is not a function
```
cause Mistaking the exported boolean value for a function and attempting to call it.

fix The package exports a direct boolean (or null) value, not a function. Use it as a variable: `if (supportsPreserveSymlinks) { ... }`.
```
ESM import 'node-supports-preserve-symlinks-flag' results in undefined or empty object
```
cause Incorrectly importing a CJS package that exports a primitive directly via `module.exports` using ESM named imports (`import { symbol } from 'package'`).

fix Use the default import syntax for CJS interop, typically `import supportsPreserveSymlinks from 'node-supports-preserve-symlinks-flag';` or dynamic import to access `default`.

Warnings

gotcha The package returns `null` when executed in a browser environment, as the concept of Node.js-specific CLI flags is irrelevant there. Be sure to handle this case if your code might run client-side.
Fix: Check for `null` explicitly: `if (supportsPreserveSymlinks === null) { /* browser-specific logic */ } else if (supportsPreserveSymlinks) { /* Node.js supported */ } else { /* Node.js not supported */ }`
gotcha This package is a CJS module. When used in a pure ESM project (e.g., with `"type": "module"` in `package.json`), direct `require()` calls are not available, and ESM `import` statements may behave differently depending on Node.js version and bundler configuration.
Fix: For ESM, consider dynamic import: `const { default: supportsPreserveSymlinks } = await import('node-supports-preserve-symlinks-flag');` or use a bundler that handles CJS interop.

Install

npm install supports-preserve-symlinks-flag npm
yarn add supports-preserve-symlinks-flag yarn
pnpm add supports-preserve-symlinks-flag pnpm

Imports

supportsPreserveSymlinks
```
const supportsPreserveSymlinks = require('node-supports-preserve-symlinks-flag');
```
This package exports a primitive boolean (or null) directly via `module.exports`.
supportsPreserveSymlinks
wrong:
```
import supportsPreserveSymlinks from 'node-supports-preserve-symlinks-flag';
```
correct:
```
import supportsPreserveSymlinks from 'node-supports-preserve-symlinks-flag';
```
While some ESM environments (like Node.js with `--experimental-modules` or bundlers) might allow this for CJS interop, it technically relies on Node.js's CJS-to-ESM wrapper for `module.exports` to become the default export. It is not a native ESM default export.
supportsPreserveSymlinks
wrong:
```
import { supportsPreserveSymlinks } from 'node-supports-preserve-symlinks-flag';
```
correct:
```
import * as supportsPreserveSymlinksModule from 'node-supports-preserve-symlinks-flag';
const supportsPreserveSymlinks = supportsPreserveSymlinksModule.default || supportsPreserveSymlinksModule;
```
This package does not use named exports. Attempting a named import (`{ supportsPreserveSymlinks }`) will result in `undefined` for the symbol. If using `import * as pkg`, the actual value might be under `pkg.default` or `pkg` directly depending on the runtime's CJS interop.

Quickstart

This example demonstrates how to import and use the package to determine `--preserve-symlinks` flag support, showing expected values for different environments.

const supportsPreserveSymlinks = require('node-supports-preserve-symlinks-flag');
const assert = require('assert');

// In a browser environment, it will be null.
// In Node.js < v6.2, it will be false.
// In Node.js v6.2+, it will be true.

console.log(`Current environment supports --preserve-symlinks: ${supportsPreserveSymlinks}`);

// Example assertions (uncomment and run in a specific Node.js version for actual results)
// assert.equal(supportsPreserveSymlinks, null); // Run in a browser for this to pass
// assert.equal(supportsPreserveSymlinks, false); // Run in Node.js < v6.2 for this to pass
// assert.equal(supportsPreserveSymlinks, true); // Run in Node.js v6.2+ for this to pass

view raw JSON →