Cross-Platform Compatibility

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Comprehensive guide to writing code that works seamlessly across Windows, macOS, and Linux. Covers file path handling, environment detection, platform-specific features, and testing strategies.

When to Use

• Building applications for multiple operating systems
• Handling file system operations
• Managing platform-specific dependencies
• Detecting operating system and architecture
• Working with environment variables
• Building cross-platform CLI tools
• Dealing with line endings and character encodings
• Managing platform-specific build processes

Quick Start

Minimal working example:

// ❌ BAD: Hardcoded paths with platform-specific separators
const configPath = "C:\\Users\\user\\config.json"; // Windows only
const dataPath = "/home/user/data.txt"; // Unix only

// ✅ GOOD: Use path module
import path from "path";
import os from "os";

// Platform-independent path construction
const configPath = path.join(os.homedir(), "config", "app.json");
const dataPath = path.join(process.cwd(), "data", "users.txt");

// Resolve relative paths
const absolutePath = path.resolve("./config/settings.json");

// Get path components
const dirname = path.dirname("/path/to/file.txt"); // '/path/to'
const basename = path.basename("/path/to/file.txt"); // 'file.txt'
const extname = path.extname("/path/to/file.txt"); // '.txt'

// Normalize paths (handle .. and .)
const normalized = path.normalize("/path/to/../file.txt"); // '/path/file.txt'

Reference Guides

Detailed implementations in the references/ directory:

Guide	Contents
File Path Handling	File Path Handling
Platform Detection	Platform Detection
Line Endings	Line Endings
Environment Variables	Environment Variables
Shell Commands	Shell Commands
File Permissions	File Permissions
Process Management	Process Management
Platform-Specific Dependencies	Platform-Specific Dependencies
Testing Across Platforms	Testing Across Platforms
Character Encoding	Character Encoding
Build Configuration	Build Configuration

Best Practices

✅ DO

• Use path.join() or path.resolve() for paths
• Use os.EOL for line endings
• Detect platform at runtime when needed
• Test on all target platforms
• Use optionalDependencies for platform-specific modules
• Handle file permissions gracefully
• Use shell escaping for user input
• Normalize line endings in text files
• Use UTF-8 encoding by default
• Document platform-specific behavior
• Provide fallbacks for platform-specific features
• Use CI/CD to test on multiple platforms

❌ DON'T

• Hardcode file paths with backslashes or forward slashes
• Assume Unix-only features (signals, permissions, symlinks)
• Ignore Windows-specific quirks (drive letters, UNC paths)
• Use platform-specific commands without fallbacks
• Assume case-sensitive file systems
• Forget about different line endings
• Use platform-specific APIs without checking
• Hardcode environment variable access patterns
• Ignore character encoding issues