# configstore

> Easily load and save config without having to think about where and how

Latest version **8.0.0** (published 2026-01-24) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install configstore
pnpm add configstore
yarn add configstore
bun add configstore
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 8.0.0 |
| Published | 2026-01-24 |
| First published | 2012-11-13 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 5 |
| Unpacked size | 11.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 891 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | config, store, storage, configuration, settings, preferences, json, data, persist, persistent, save |

## Links

- npm: https://www.npmjs.com/package/configstore
- Repository: https://github.com/sindresorhus/configstore
- Homepage: https://github.com/sindresorhus/configstore#readme
- Issues: https://github.com/sindresorhus/configstore/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/configstore

## Dependencies (5)

- [dot-prop](https://npm.io/package/dot-prop.md) ^10.1.0
- [atomically](https://npm.io/package/atomically.md) ^2.1.0
- [graceful-fs](https://npm.io/package/graceful-fs.md) ^4.2.11
- [xdg-basedir](https://npm.io/package/xdg-basedir.md) ^5.1.0
- [is-safe-filename](https://npm.io/package/is-safe-filename.md) ^0.1.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 8.0.0 (latest) — 2026-01-24
- 3.1.5 (legacy-v3) — 2020-08-16
- 7.1.0 — 2025-09-15
- 7.0.0 — 2024-07-13
- 6.0.0 — 2021-04-05
- 3.1.4 — 2020-08-14
- 3.1.3 — 2020-08-14
- 5.0.1 — 2020-02-13
- 5.0.0 — 2019-06-11
- 4.0.0 — 2018-07-28
- 3.1.2 — 2018-03-26
- 3.1.1 — 2017-07-20
- 3.1.0 — 2017-05-10
- 3.0.0 — 2017-02-13
- 2.1.0 — 2016-09-01
- … 22 more at https://npm.io/package/configstore/versions

## README

# configstore

> Easily load and persist config without having to think about where and how

The config is stored in a JSON file located in `$XDG_CONFIG_HOME` or `~/.config`.\
Example: `~/.config/configstore/some-id.json`

*If you need this for Electron, check out [`electron-store`](https://github.com/sindresorhus/electron-store) instead.*\
*And check out [`conf`](https://github.com/sindresorhus/conf) for a more modern version of `configstore`.*

## Install

```sh
npm install configstore
```

## Usage

```js
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
```

## API

### Configstore(id, defaults?, options?)

Returns a new instance.

#### id

Type: `string`

Identifier for your config. Usually your package name.

#### defaults

Type: `object`

Default config.

#### options

Type: `object`

##### globalConfigPath

Type: `boolean`\
Default: `false`

Store the config at `$CONFIG/package-name/config.json` instead of the default `$CONFIG/configstore/package-name.json`. This is not recommended as you might end up conflicting with other tools, rendering the "without having to think" idea moot.

##### configPath

Type: `string`\
Default: Automatic

**Please don't use this option unless absolutely necessary and you know what you're doing.**

Set the path of the config file. Overrides the `id` and `globalConfigPath` options.

##### clearInvalidConfig

Type: `boolean`\
Default: `true`

Clear the config file if it contains invalid JSON. If set to `false`, a `SyntaxError` will be thrown instead of clearing the file. This allows you to recover corrupted config files manually.

### Instance

You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a `key` to access nested properties.

### .set(key, value)

Set an item.

You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a `key` to access nested properties.

### .set(object)

Set multiple items at once.

### .get(key)

Get an item.

You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a `key` to access nested properties.

> [!TIP]
> Use the [nullish coalescing operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`) to provide default values:
> ```js
> const value = config.get('key') ?? 'default value';
> ```

### .has(key)

Check if an item exists.

You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a `key` to access nested properties.

### .delete(key)

Delete an item.

You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a `key` to access nested properties.

### .clear()

Delete all items.

### .size

Get the item count.

### .path

Get the path to the config file. Can be used to show the user where the config file is located or even better open it for them.

### .all

Get all the config as an object or replace the current config with an object.

```js
console.log(config.all);
//=> {foo: 'bar', hello: 'world'}

config.all = {
	hello: 'world'
};
```

---
_Source: https://npm.io/package/configstore · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._