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.
import path from 'node:path'; const file = path.join('data', 'users', 'list.json'); // data/users/list.json or data\users\list.json
Try it
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.
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 forSIGTERMnever run. UseSIGINTplus an application-level shutdown message for portability, as in Graceful shutdown. - Environment variables. Windows names are case insensitive in practice (
PathversusPATH);process.envfollows 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-fileor a helper. - Shebang scripts.
#!/usr/bin/env nodeis read on Unix; npm creates.cmdshims on Windows forbinentries. - Symlinks need special privilege or developer mode on Windows; code that creates them should handle
EPERM. - Line endings in git. Configure
.gitattributesso scripts keep\n; a shebang with\rbreaks on Linux. - Home and temp folders: use
os.homedir()andos.tmpdir()rather than hard-coded/tmpor~. - Test where you deploy. Run CI on every operating system you support, and use
path.posixorpath.win32explicitly 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.