or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

env-paths

env-paths provides cross-platform, OS-specific paths for storing application data, configuration files, cache, logs, and temporary files. It follows platform conventions including XDG Base Directory Specification on Linux, macOS Library structure, and Windows AppData directories.

Package Information

Package Name: env-paths
Package Type: npm
Language: JavaScript (ES modules)
Installation: npm install env-paths

Core Imports

import envPaths from "env-paths";

Note: This package is ES modules only and requires Node.js 12.20.0 or later.

Basic Usage

import envPaths from "env-paths";

// Get paths for your application
const paths = envPaths('MyApp');

console.log(paths.data);
//=> '/home/user/.local/share/MyApp-nodejs' (Linux)
//=> '/Users/user/Library/Application Support/MyApp-nodejs' (macOS)
//=> 'C:\Users\user\AppData\Local\MyApp-nodejs\Data' (Windows)

console.log(paths.config);
//=> '/home/user/.config/MyApp-nodejs' (Linux)
//=> '/Users/user/Library/Preferences/MyApp-nodejs' (macOS)
//=> 'C:\Users\user\AppData\Roaming\MyApp-nodejs\Config' (Windows)

// Without default suffix
const customPaths = envPaths('MyApp', { suffix: '' });
console.log(customPaths.data);
//=> '/home/user/.local/share/MyApp' (Linux)

// Alternative: disable suffix with false
const noSuffixPaths = envPaths('MyApp', { suffix: false });
console.log(noSuffixPaths.data);
//=> '/home/user/.local/share/MyApp' (Linux)

// Custom suffix
const hornPaths = envPaths('MyApp', { suffix: 'horn' });
console.log(hornPaths.data);
//=> '/home/user/.local/share/MyApp-horn' (Linux)

Architecture

env-paths uses platform detection to provide OS-appropriate directory paths following established conventions:

Platform Detection: Uses process.platform to identify the operating system (darwin, win32, or others)
Path Resolution Strategy: Each platform has dedicated logic for resolving standard directories
Standards Compliance:
- Linux/Unix: Follows XDG Base Directory Specification
- macOS: Uses standard macOS Library structure (~/Library/Application Support, ~/Library/Preferences, etc.)
- Windows: Leverages Windows environment variables (%APPDATA%, %LOCALAPPDATA%)
Suffix Management: Automatically appends -nodejs suffix (or custom suffix) to prevent conflicts with native applications
Environment Variable Awareness: Respects XDG environment variables on Linux systems when available

This design ensures cross-platform compatibility while following platform-specific best practices for application data storage.

Capabilities

Path Generation

Returns OS-appropriate directory paths for storing different types of application data.

/**
 * Get paths for storing things like data, config, cache, etc.
 * Note: Only generates path strings - doesn't create directories.
 * 
 * @param name - The name of your project. Used to generate the paths.
 * @param options - Configuration options
 * @returns Object containing OS-specific directory paths
 * @throws TypeError if name is not a string
 */
function envPaths(name: string, options?: Options): Paths;

interface Options {
  /**
   * Don't use this option unless you really have to!
   * Suffix appended to the project name to avoid name conflicts with native apps.
   * Pass an empty string or false to disable it.
   * @default 'nodejs'
   */
  readonly suffix?: string | false;
}

interface Paths {
  /** Directory for data files */
  readonly data: string;
  /** Directory for config files */
  readonly config: string;
  /** Directory for non-essential data files */
  readonly cache: string;
  /** Directory for log files */
  readonly log: string;
  /** Directory for temporary files */
  readonly temp: string;
}

Platform-Specific Paths

The function returns different paths based on the operating system:

macOS (darwin):

data: ~/Library/Application Support/{name}
config: ~/Library/Preferences/{name}
cache: ~/Library/Caches/{name}
log: ~/Library/Logs/{name}
temp: {tmpdir}/{name}

Windows (win32):

data: %LOCALAPPDATA%\{name}\Data
config: %APPDATA%\{name}\Config
cache: %LOCALAPPDATA%\{name}\Cache
log: %LOCALAPPDATA%\{name}\Log
temp: {tmpdir}\{name}

Linux (and other Unix-like systems): Follows XDG Base Directory Specification:

data: $XDG_DATA_HOME/{name} or ~/.local/share/{name}
config: $XDG_CONFIG_HOME/{name} or ~/.config/{name}
cache: $XDG_CACHE_HOME/{name} or ~/.cache/{name}
log: $XDG_STATE_HOME/{name} or ~/.local/state/{name}
temp: /tmp/{username}/{name}

Usage Examples

Basic application setup:

import envPaths from "env-paths";
import fs from "fs/promises";
import path from "path";

const paths = envPaths('my-cli-tool');

// Create directories as needed
await fs.mkdir(paths.data, { recursive: true });
await fs.mkdir(paths.config, { recursive: true });

// Store configuration
const configFile = path.join(paths.config, 'settings.json');
await fs.writeFile(configFile, JSON.stringify({ theme: 'dark' }));

// Store data
const dataFile = path.join(paths.data, 'cache.db');
// ... use dataFile for data storage

Without default suffix (not recommended):

import envPaths from "env-paths";

// Removes '-nodejs' suffix - use cautiously to avoid conflicts
const paths = envPaths('MyApp', { suffix: '' });
console.log(paths.data);
//=> '/home/user/.local/share/MyApp'

// Alternative: disable suffix with false
const pathsNoSuffix = envPaths('MyApp', { suffix: false });
console.log(pathsNoSuffix.data);
//=> '/home/user/.local/share/MyApp'

Custom suffix:

import envPaths from "env-paths";

// Use custom suffix instead of default 'nodejs'
const paths = envPaths('MyApp', { suffix: 'electron' });
console.log(paths.data);
//=> '/home/user/.local/share/MyApp-electron'

Error Handling

The function throws a TypeError if the name parameter is not a string:

try {
  const paths = envPaths(123); // Will throw TypeError
} catch (error) {
  console.error(error.message);
  // "Expected a string, got number"
}