1.3.2

@cross/dir 1.3.2

Fixes

• Returned paths are now normalized. . and .. segments, duplicate separators and trailing separators are
  removed. For example, on Linux with XDG_DATA_HOME set, executable now returns ~/.local/bin instead of
  ~/.local/share/../bin, and on macOS tmp no longer ends with a /. The directories themselves are unchanged.

Internal

• CI now runs the test suite on Linux, Windows and macOS, and logs the resolved path for every directory type.
• Added a Windows test that verifies the shell:Downloads lookup introduced in 1.3.0.

1.3.1

@cross/dir 1.3.1

Error classes

dir() now throws typed errors, both extending Error with type and platform properties:

• UnsupportedDirectoryError: the directory type is unknown or not available on the current platform.
• DirectoryNotFoundError: the type is supported, but its path could not be resolved on this system.

import { dir, DirectoryNotFoundError } from "@cross/dir";

try {
    await dir("projects");
} catch (error) {
    if (error instanceof DirectoryNotFoundError) { /* ... */ }
}

Error messages are unchanged. The only exception is the Windows hint, which now refers to the new option.

Options object

dir() now accepts an options object as its second argument:

await dir("download", { windowsSpecialFolders: true });

Passing a boolean (dir("download", true)) still works but is deprecated and will be removed in 2.0.

New directory type: preference

Resolves to the same path as config on Linux and Windows, and to ~/Library/Preferences on macOS.

On macOS, config currently points to ~/Library/Preferences, which Apple reserves for system-managed .plist
files. It is planned to move to ~/Library/Application Support in 2.0. If you rely on the current location, switch to
preference now.

Fixes

- Windows: download now resolves the actual Downloads location through the shell's known folder
  (shell:Downloads), so relocated Downloads folders are found. It falls back to %USERPROFILE%\Downloads if that
  lookup fails. This requires the windowsSpecialFolders option, as before.

Deprecations (removal planned for 2.0)

- Boolean second argument to dir(). Use { windowsSpecialFolders: true } instead.

1.3.0

@cross/dir 1.3.0

Error classes

dir() now throws typed errors, both extending Error with type and platform properties:

• UnsupportedDirectoryError: the directory type is unknown or not available on the current platform.
• DirectoryNotFoundError: the type is supported, but its path could not be resolved on this system.

import { dir, DirectoryNotFoundError } from "@cross/dir";

try {
    await dir("projects");
} catch (error) {
    if (error instanceof DirectoryNotFoundError) { /* ... */ }
}

Error messages are unchanged. The only exception is the Windows hint, which now refers to the new option.

Options object

dir() now accepts an options object as its second argument:

await dir("download", { windowsSpecialFolders: true });

Passing a boolean (dir("download", true)) still works but is deprecated and will be removed in 2.0.

New directory type: preference

Resolves to the same path as config on Linux and Windows, and to ~/Library/Preferences on macOS.

On macOS, config currently points to ~/Library/Preferences, which Apple reserves for system-managed .plist
files. It is planned to move to ~/Library/Application Support in 2.0. If you rely on the current location, switch to
preference now.

Fixes

- Windows: download now resolves the actual Downloads location through the shell's known folder
  (shell:Downloads), so relocated Downloads folders are found. It falls back to %USERPROFILE%\Downloads if that
  lookup fails. This requires the windowsSpecialFolders option, as before.

Deprecations (removal planned for 2.0)

- Boolean second argument to dir(). Use { windowsSpecialFolders: true } instead.

1.2.0

@cross/dir 1.2.0

Linux: user directories now work out of the box

download, document, audio, picture, video, desktop, public and template previously only resolved if
their XDG_*_DIR environment variable was set, which most desktop sessions don't do. They are now also read from
the xdg-user-dirs file $XDG_CONFIG_HOME/user-dirs.dirs
(default ~/.config/user-dirs.dirs). Environment variables still take precedence.

Entries pointing to the home directory itself (e.g. XDG_DESKTOP_DIR="$HOME/") are treated as disabled, per the
xdg-user-dirs spec, and still throw.

New directory types

• projects (Linux): resolves XDG_PROJECTS_DIR, added in xdg-user-dirs 0.19.
• state (all platforms): for persistent application state such as logs and history.
  • Linux: $XDG_STATE_HOME, falling back to ~/.local/state
  • macOS: ~/Library/Application Support
  • Windows: %LOCALAPPDATA%

Fixes

• Windows: the PowerShell fallback for config (dir("config", true) with APPDATA unset) now returns the
  roaming ApplicationData folder instead of LocalApplicationData, consistent with APPDATA and data.
• Windows: tmp now falls back to TEMP when TMP is unset.

Internal

• Added a test suite (deno task test), including a platform smoke test that resolves every directory type.
• Removed the unused @cross/deepmerge dependency.
• Fixed the check-deps task flag (--ignore-unused → --allow-unused) so deno task check passes.
• README: added error handling and development sections, and fixed the usage example's missing DirectoryTypes import.

Upgrade impact: nothing needs to change for most people. The one exception is a Windows call to dir("config", true) on a machine where APPDATA isn't set. Before, that returned ...\AppData\Local; now it returns ...\AppData\Roaming. That's rare, since Windows normally sets APPDATA, but anyone who relied on the old path would stop finding files they stored there.

1.1.1

• Windows: dir("public") is now supported and resolves via the %PUBLIC% environment variable (FOLDERID_Public, e.g. C:\Users\Public).

Full Changelog: 1.1.0...1.1.1

1.1.0

Changes

• Added "/tmp" as a fallback directory for linux and the temp directory type.
• Added a second optional parameter for the dir() function that you set to true to opt-into resolving Windows Special Folders with powershell.

const userHome = await dir("home", true);

Full Changelog: 1.0.1...1.1.0

1.0.1

• Using @cross/runtime for OS detection.

Full Changelog: 1.0.0...1.0.1

1.0.0

@cross/dir v1.0.0

Key Features

• Cross-Platform Compatibility: Retrieve standard user directory paths on Windows, macOS, and Linux for Deno, Bun, and Node.js projects.
• Essential Directories: Supports common directories like home, cache, config, data, download, tmp, and more.
• Reliability: Uses established environment variables and platform-specific techniques for accurate results.
• TypeScript-Ready: Includes TypeScript definitions for type safety and improved development experience.
• Easy Installation: Add to your project with a single command for Deno, Bun, or Node.js.

For documentation and usage see dir on JSR.io

Full Changelog: https://github.com/cross-org/dir/commits/1.0.0