{"id":12104,"library":"supports-preserve-symlinks-flag","title":"Node.js --preserve-symlinks Flag Support","description":"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.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/inspect-js/node-supports-preserve-symlinks-flag","tags":["javascript","node","flag","symlink","symlinks","preserve-symlinks"],"install":[{"cmd":"npm install supports-preserve-symlinks-flag","lang":"bash","label":"npm"},{"cmd":"yarn add supports-preserve-symlinks-flag","lang":"bash","label":"yarn"},{"cmd":"pnpm add supports-preserve-symlinks-flag","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package exports a primitive boolean (or null) directly via `module.exports`.","symbol":"supportsPreserveSymlinks","correct":"const supportsPreserveSymlinks = require('node-supports-preserve-symlinks-flag');"},{"note":"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.","wrong":"import supportsPreserveSymlinks from 'node-supports-preserve-symlinks-flag';","symbol":"supportsPreserveSymlinks","correct":"import supportsPreserveSymlinks from 'node-supports-preserve-symlinks-flag';"},{"note":"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.","wrong":"import { supportsPreserveSymlinks } from 'node-supports-preserve-symlinks-flag';","symbol":"supportsPreserveSymlinks","correct":"import * as supportsPreserveSymlinksModule from 'node-supports-preserve-symlinks-flag';\nconst supportsPreserveSymlinks = supportsPreserveSymlinksModule.default || supportsPreserveSymlinksModule;"}],"quickstart":{"code":"const supportsPreserveSymlinks = require('node-supports-preserve-symlinks-flag');\nconst assert = require('assert');\n\n// In a browser environment, it will be null.\n// In Node.js < v6.2, it will be false.\n// In Node.js v6.2+, it will be true.\n\nconsole.log(`Current environment supports --preserve-symlinks: ${supportsPreserveSymlinks}`);\n\n// Example assertions (uncomment and run in a specific Node.js version for actual results)\n// assert.equal(supportsPreserveSymlinks, null); // Run in a browser for this to pass\n// assert.equal(supportsPreserveSymlinks, false); // Run in Node.js < v6.2 for this to pass\n// assert.equal(supportsPreserveSymlinks, true); // Run in Node.js v6.2+ for this to pass\n","lang":"javascript","description":"This example demonstrates how to import and use the package to determine `--preserve-symlinks` flag support, showing expected values for different environments."},"warnings":[{"fix":"Check for `null` explicitly: `if (supportsPreserveSymlinks === null) { /* browser-specific logic */ } else if (supportsPreserveSymlinks) { /* Node.js supported */ } else { /* Node.js not supported */ }`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For ESM, consider dynamic import: `const { default: supportsPreserveSymlinks } = await import('node-supports-preserve-symlinks-flag');` or use a bundler that handles CJS interop.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` directly in a pure ES module (`.mjs` file or `\"type\": \"module\"` package).","error":"ReferenceError: require is not defined"},{"fix":"The package exports a direct boolean (or null) value, not a function. Use it as a variable: `if (supportsPreserveSymlinks) { ... }`.","cause":"Mistaking the exported boolean value for a function and attempting to call it.","error":"TypeError: supportsPreserveSymlinks is not a function"},{"fix":"Use the default import syntax for CJS interop, typically `import supportsPreserveSymlinks from 'node-supports-preserve-symlinks-flag';` or dynamic import to access `default`.","cause":"Incorrectly importing a CJS package that exports a primitive directly via `module.exports` using ESM named imports (`import { symbol } from 'package'`).","error":"ESM import 'node-supports-preserve-symlinks-flag' results in undefined or empty object"}],"ecosystem":"npm"}