dirs-next

dirs-next is a small, dependency-light Rust crate that resolves the platform-specific standard directories for configuration, cache, and application data on Linux, macOS, Windows, and Redox. It wraps the XDG Base Directory specification on Linux, the Known Folder API on Windows, and Apple’s Standard Directories guidelines on macOS behind a single, consistent function-per-directory API, so applications don’t need to hand-roll OS-specific path logic.

It is a community-maintained fork of the original, once-abandoned dirs crate, published under the xdg-rs organization alongside its mid-level sibling directories-next and the low-level platform bindings crate dirs-sys-next. The crate exposes 16 functions covering everything from home_dir and config_dir to more specific locations like download_dir, font_dir, and runtime_dir, each returning an Option<PathBuf> that is None when the platform has no equivalent concept.

What You Get

• 16 functions covering home, config, cache, data, and OS-specific user directories (Desktop, Downloads, Music, Pictures, etc.)
• Consistent XDG Base Directory behavior on Linux/Redox, Known Folder API on Windows, and Apple guideline paths on macOS
• A minimal dependency footprint via the companion dirs-sys-next crate for the raw platform bindings
• WASM target support in addition to the three desktop platforms

Common Use Cases

• Resolving where a CLI tool should read/write its config file across platforms
• Locating a safe, OS-appropriate cache directory for a build tool or package manager
• Finding the user’s Downloads or Documents folder for a desktop GUI app’s file picker default
• Building higher-level app-specific path helpers (e.g. via directories-next’s ProjectDirs) on top of the base directories this crate returns

Under The Hood

Architecture: dirs-next’s public surface lives entirely in src/lib.rs, which declares 16 documented functions (home_dir, cache_dir, config_dir, data_dir, data_local_dir, executable_dir, runtime_dir, and nine user-directory functions like desktop_dir/download_dir) that each delegate to a single conditionally-compiled sys module. The #[path] cfg-gated module aliasing at the top of lib.rs (mod sys pointing at win.rs, mac.rs, wasm.rs, or lin.rs depending on target) is the crate’s only real architectural device: it lets every public function be a one-line call into sys::* while the actual platform logic — reading $XDG_* env vars and falling back to $HOME joins on Linux (lin.rs), joining fixed Library/... subpaths under $HOME on macOS (mac.rs), calling into the separate dirs-sys-next crate’s known_folder_* Windows API wrappers (win.rs), or returning None stubs for wasm32 (wasm.rs) — is fully isolated per platform. There is no shared state, no runtime configuration, and no dynamic dispatch: each call performs its lookup fresh, and cross-platform consistency is achieved by convention (same function names, same Option<PathBuf> return type) rather than a shared trait or interface.

Tech Stack: The published dirs crate (Cargo.toml name dirs-next, version 2.0.0, edition 2018) has zero direct dependencies of its own beyond a workspace-path dependency on dirs-sys-next 0.1, the sibling crate in the same xdg-rs/dirs Cargo workspace that wraps libc (Unix) and Windows Known Folder APIs. The workspace root Cargo.toml defines three members — dirs-sys, dirs, directories — with dirs as the default member, built with #![deny(missing_docs)] and #![warn(rust_2018_idioms)] lint attributes enforcing documentation coverage and idiomatic style. Minimum supported Rust version is pinned at 1.34.0 per the README’s stated policy, and CI (bors.toml, .github/) cross-compiles against linux-gnu, windows-gnu, apple-darwin, and unknown-redox targets to verify each platform module actually builds.

Code Quality: Tests are minimal and platform-oriented rather than exhaustive: lib.rs has a single #[cfg(test)] mod tests that calls every public function and prints its result (a smoke test verifying nothing panics, not an assertion-based test), and lin.rs adds one Linux-only test checking for a user-dirs.dirs file’s existence. There are no unit tests asserting exact path values, no mocked-environment tests for the XDG env-var fallback logic, and no tests at all in win.rs, mac.rs, or wasm.rs. Error handling is uniformly Option<PathBuf>-based — every function returns None rather than erroring when a directory can’t be determined (e.g. executable_dir and runtime_dir on macOS/Windows, template_dir on macOS) — a defensible, idiomatic choice for a library whose failure mode is genuinely ‘this platform has no such directory,’ not an exceptional error. Naming is consistent and predictable (*_dir suffix throughout), and every public function carries a full doc comment with a platform-by-platform value table, giving the crate strong documentation density despite thin test coverage.

API Design: The API is about as low-friction as a Rust crate gets: 16 free functions, no traits to implement, no builder pattern, no configuration struct — calling dirs_next::config_dir() is the entire integration. Every function shares the same fn() -> Option<PathBuf> signature, so once a developer learns one function they know all sixteen, and the Option return type is the correct, unsurprising way to express ‘this directory concept doesn’t exist on this platform’ without forcing callers into error-handling boilerplate for a non-error condition. The tradeoff is that the crate covers only the base directories: for anything project-scoped (e.g. ‘my app’s own config subdirectory’), the README explicitly directs users to the companion directories-next crate’s ProjectDirs API, keeping this crate’s DX simple by design rather than accidentally. Documentation is thorough — every function’s rustdoc includes a per-platform table with concrete example paths — but the top-level workspace README also carries a maintenance-status note (pointing to github.com/dirs-dev as the crates’ current home), which is worth surfacing to a developer evaluating long-term support.