Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

Cross-platform pitfalls in Node.js

Write Node.js code that runs on Windows, macOS and Linux: path separators, line endings, case sensitivity, file modes, signals, shells and file URLs.

Node.js runs on Windows, macOS and Linux with one API, but the operating systems underneath still differ. Most portability bugs come from a short list of assumptions: how paths are written, what ends a line, whether file names are case sensitive, what a file mode means, and which signals exist. Code that is written with these in mind runs everywhere; code that ignores them works on the developer's machine and fails in CI or production.

The rule of thumb: let Node's own modules (path, os, url, fs) do the platform-specific work, and never build paths or detect platforms by hand with string operations.

NODE
import path from 'node:path';
const file = path.join('data', 'users', 'list.json');   // data/users/list.json or data\users\list.json

Try it

Node.js Paths and file URLs on both systems

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Line endings, case and file modes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The differences that matter

Area Windows Linux / macOS What to do
Path separator \ (and / accepted) / Use path.join(), path.resolve(), never 'a' + '/' + 'b'.
Drive letters C:\ roots, UNC paths Single root / Use path.isAbsolute() and path.parse().
Line endings \r\n \n Split with /\r?\n/; use os.EOL only when writing for the local system.
Case in file names Insensitive Linux sensitive; macOS usually not Keep exact names; do not rely on case to tell files apart.
File modes chmod mostly ignored (only read-only flag) Full rwx bits Do not depend on 0o600 on Windows; protect secrets by other means.
Reserved names CON, NUL, AUX, trailing dots Almost none Validate user-provided file names.
Signals SIGINT and SIGBREAK from the console; SIGTERM not delivered Full set Do not assume SIGTERM; see below.
Shell cmd.exe or PowerShell /bin/sh Avoid exec('rm -rf ...'); use fs.rm().
Executables .exe, .cmd, .bat Mode bit and shebang Use spawn with shell carefully or cross-spawn-style handling for .cmd.
Max path length 260 characters by default in many tools About 4096 Keep paths short on Windows.

Usage notes

  • Signals. On Windows, process.kill(pid, 'SIGTERM') ends the process abruptly instead of delivering a signal, and handlers for SIGTERM never run. Use SIGINT plus an application-level shutdown message for portability, as in Graceful shutdown.
  • Environment variables. Windows names are case insensitive in practice (Path versus PATH); process.env follows the system's rule, so use one spelling consistently. Setting variables inline (NAME=x node app.js) is shell syntax that Windows lacks; use --env-file or a helper.
  • Shebang scripts. #!/usr/bin/env node is read on Unix; npm creates .cmd shims on Windows for bin entries.
  • Symlinks need special privilege or developer mode on Windows; code that creates them should handle EPERM.
  • Line endings in git. Configure .gitattributes so scripts keep \n; a shebang with \r breaks on Linux.
  • Home and temp folders: use os.homedir() and os.tmpdir() rather than hard-coded /tmp or ~.
  • Test where you deploy. Run CI on every operating system you support, and use path.posix or path.win32 explicitly when you work with paths from another system than the current one.
  • Spaces and non-ASCII characters in paths are common on Windows (C:\Users\Jane Doe\...). Pass arguments as arrays instead of building command strings.