Safe Cross-Platform Path Manipulation in Dart

Contents

• 1. Core Principles & Cross-Platform Rules
• 2. Recommended package:path Idioms vs. String Anti-Patterns
• 3. Bridging Native Paths to POSIX, Git, & URL Contexts
• 4. Mockable File Systems (package:file vs. Global p.*)
• 5. Extensions, Compound Extensions & Stem Extraction
• 6. Workflows & Audit Checklist
• References & Examples

1. Core Principles & Cross-Platform Rules

Avoid Treating File Paths as Raw Strings

• Native file paths on Windows use backslashes (\), whereas macOS and Linux use forward slashes (/).
• String operations like .contains('foo/'), .startsWith('foo/'), or .split('/') silently fail on Windows native paths.
• String interpolation like '$dir/$file' injects forward slashes on Windows and produces duplicate slashes (//) when $dir ends with a trailing slash.