DOCSEARCHbyAlgolia
Submit Docs

configstore

repository·main·Indexed 21 days ago

https://github.com/sindresorhus/configstore

A utility for loading and persisting configuration data in JSON files, abstracting file system logic and path management. It typically stores data in XDG-compliant directories and supports dot-notation for accessing nested properties. Version 8.0.0.

Tokens
2.4K
Snippets
11
Records
19
Agent score
25%

What's inside configstore

  1. Quickstart using configstore

    main

    To use configstore, import the class, instantiate it with a unique identifier (like your package name), and use the instance methods to manage data. It supports dot-notation for accessing nested properties.

    import fs from 'node:fs';
import Configstore from 'configstore';

const packageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));

// Create a Configstore instance.
const config = new Configstore(packageJson.name, {foo: 'bar'});

console.log(config.get('foo'));
//=> 'bar'

config.set('awesome', true);
console.log(config.get('awesome'));
//=> true

// Use dot-notation to access nested properties.
config.set('bar.baz', true);
console.log(config.get('bar'));
//=> {baz: true}

// Handle missing keys with nullish coalescing.
console.log(config.get('nonexistent') ?? 'default value');
//=> 'default value'

config.delete('awesome');
console.log(config.get('awesome'));
//=> undefined

  3. Handle invalid JSON configuration

    main

    If the configuration file contains invalid JSON, Configstore behavior depends on the clearInvalidConfig option provided during instantiation (which defaults to true).

    • If clearInvalidConfig is true: The invalid file is overwritten with an empty string (effectively an empty object {}), and the error is suppressed.
    • If clearInvalidConfig is false: A SyntaxError is thrown when attempting to access all or any method that reads from the store.

    Note on Permissions: If the process lacks permission to read or write the file, an error with the message You don't have access to this file. will be appended to the original error.

  4. Initialize a new Configstore instance

    main

    Use the Configstore constructor to create a new instance. The configuration is stored in a JSON file located in $XDG_CONFIG_HOME or ~/.config (e.g., ~/.config/configstore/some-id.json).

    new Configstore(id, defaults?, options?)

  6. Configstore constructor parameters

    main

    Parameters

    • id (string): Identifier for your config. Usually your package name.
    • defaults (object): Default config values.
    • options (object): Configuration options for the instance.

    Options

    • globalConfigPath (boolean, default: false): If true, stores the config at $CONFIG/package-name/config.json instead of the default $CONFIG/configstore/package-name.json. Not recommended as it may conflict with other tools.
    • configPath (string, default: Automatic): Set the specific path of the config file. Overrides id and globalConfigPath. Use only if absolutely necessary.
    • clearInvalidConfig (boolean, default: true): If true, the config file is cleared if it contains invalid JSON. If false, a SyntaxError is thrown, allowing for manual recovery of corrupted files.

  7. Initialize Configstore

    main

    Create a new Configstore instance by providing a unique id. The id must be a safe filename. By default, configuration is stored in the XDG config directory (or a temporary directory if XDG is not available) under a configstore/ subdirectory. You can provide defaults to pre-populate the store, and options to customize the storage location or behavior.

    import Configstore from 'configstore';

// Basic usage
const config = new Configstore('my-app-id');

// Usage with defaults and custom options
const config = new Configstore('my-app-id', { foo: 'bar' }, {
	// Specify a custom path instead of the default XDG location
	configPath: '/path/to/custom/config.json',
	// If true (default), invalid JSON files will be cleared
	clearInvalidConfig: true
});

  8. Access all configuration and file path

    main

    The Configstore instance provides two read-only properties:

    • all: Returns the entire configuration object as a plain JavaScript object. Accessing this property reads the file from disk.
    • path: Returns the absolute string path to the JSON configuration file used by this instance.
    const config = new Configstore('my-app');

// Get the full config object
const fullConfig = config.all;

// Get the file path
console.log(config.path);

// Get the number of keys in the config
console.log(config.size);

  9. Access all config with .all

    main

    The .all property can be used to either get the entire configuration as an object or replace the current configuration with a new object.

    // Get all config
console.log(config.all);

// Replace current config
config.all = {
	hello: 'world'
};