# rc9

> Read/Write config couldn't be easier!

Latest version **3.1.0** (published 2026-09-02) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 70/100 (B)** — status: active.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2026-09-02 |
| First published | 2020-05-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 21.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 313 |
| Maintainers | pi0 |

## Links

- npm: https://www.npmjs.com/package/rc9
- Repository: https://github.com/unjs/rc9
- Homepage: https://github.com/unjs/rc9#readme
- Issues: https://github.com/unjs/rc9/issues
- npm.io page: https://npm.io/package/rc9

## Dependencies (2)

- [defu](https://npm.io/package/defu.md) ^6.1.7
- [destr](https://npm.io/package/destr.md) ^2.0.5

## Recent versions

- 3.1.0 (latest) — 2026-09-02
- 1.2.4 (1x) — 2022-11-16
- 3.0.1 — 2026-04-01
- 3.0.0 — 2026-02-06
- 2.1.2 — 2024-04-09
- 2.1.1 — 2023-06-20
- 2.1.0 — 2023-03-30
- 2.0.1 — 2023-01-24
- 2.0.0 — 2022-11-15
- 1.2.3 — 2022-11-15
- 1.2.2 — 2022-04-07
- 1.2.1 — 2022-04-07
- 1.2.0 — 2020-11-25
- 1.1.0 — 2020-11-09
- 1.0.0 — 2020-06-16
- … 8 more at https://npm.io/package/rc9/versions

## README

# RC9

<!-- automd:badges color=yellow codecov bundlejs -->

[![npm version](https://img.shields.io/npm/v/rc9?color=yellow)](https://npmjs.com/package/rc9)
[![npm downloads](https://img.shields.io/npm/dm/rc9?color=yellow)](https://npm.chart.dev/rc9)
[![bundle size](https://img.shields.io/bundlejs/size/rc9?color=yellow)](https://bundlejs.com/?q=rc9)
[![codecov](https://img.shields.io/codecov/c/gh/unjs/rc9?color=yellow)](https://codecov.io/gh/unjs/rc9)

<!-- /automd -->

Read/Write RC configs couldn't be easier!

## Install

Install dependencies:

<!-- automd:pm-i -->

```sh
# ✨ Auto-detect
npx nypm install rc9

# npm
npm install rc9

# yarn
yarn add rc9

# pnpm
pnpm add rc9

# bun
bun install rc9

# deno
deno install npm:rc9
```

<!-- /automd -->

Import utils:

<!-- automd:jsimport src="./src/index.ts"-->

**ESM** (Node.js, Bun, Deno)

```js
import {
  defaults,
  parse,
  parseFile,
  read,
  readUser,
  serialize,
  write,
  writeUser,
  userConfigDir,
  readUserConfig,
  writeUserConfig,
  updateUserConfig,
  update,
  updateUser,
} from "rc9";
```

<!-- /automd -->

## Usage

`.conf`:

```ini
db.username=username
db.password=multi word password
db.enabled=true
```

**Update config:**

```ts
update({ "db.enabled": false }); // or update(..., { name: '.conf' })
```

Push to an array:

```ts
update({ "modules[]": "test" });
```

**Read/Write config:**

```ts
const config = read(); // or read('.conf')

// config = {
//   db: {
//     username: 'username',
//     password: 'multi word password',
//     enabled: true
//   }
// }

config.enabled = false;
write(config); // or write(config, '.conf')
```

**User Config:**

You can use `readUserConfig`/`writeUserConfig`/`updateUserConfig` to store config in the user's config directory (`$XDG_CONFIG_HOME` or `~/.config`):

```js
writeUserConfig({ token: 123 }, ".zoorc"); // Will be saved in ~/.config/.zoorc

const conf = readUserConfig(".zoorc"); // { token: 123 }
```

The config directory is created if it doesn't exist. Use `userConfigDir()` if you need to know where a value was written.

> [!NOTE]
> `readUser`/`writeUser`/`updateUser` are deprecated. Use `readUserConfig`/`writeUserConfig`/`updateUserConfig` instead, which follow XDG conventions (`~/.config`).

## Unflatten

RC uses [flat](https://www.npmjs.com/package/flat) to automatically flat/unflat when writing and reading rcfile.

It means that you can use `.` for keys to define objects. Some examples:

- `hello.world = true` <=> `{ hello: { world: true }`
- `test.0 = A` <=> `tags: [ 'A' ]`

**Note:** If you use keys that can override like `x=` and `x.y=`, you can disable this feature by passing `flat: true` option.

**Tip:** You can use keys ending with `[]` to push to an array like `test[]=A`

## Native Values

RC uses [destr](https://www.npmjs.com/package/destr) to convert values into native javascript values.

So reading `count=123` results `{ count: 123 }` (instead of `{ count: "123" }`) if you want to preserve strings as is, can use `count="123"`.

## Exports

```ts
const defaults: RCOptions;
function parse(contents: string, options?: RCOptions): RC;
function parseFile(path: string, options?: RCOptions): RC;
function read(options?: RCOptions | string): RC;
function readUserConfig(options?: RCOptions | string): RC;
function userConfigDir(): string;
function serialize(config: RC): string;
function write(config: RC, options?: RCOptions | string): void;
function writeUserConfig(config: RC, options?: RCOptions | string): void;
function update(config: RC, options?: RCOptions | string): RC;
function updateUserConfig(config: RC, options?: RCOptions | string): RC;
```

**Types:**

```ts
type RC = Record<string, any>;
interface RCOptions {
  name?: string;
  dir?: string;
  flat?: boolean;
}
```

**Defaults:**

```ini
{
  name: '.conf',
  dir: process.cwd(),
  flat: false
}
```

### Why RC9?

Be the first one to guess 🐇 <!-- Hint: do research about rc files history -->

## License

<!-- automd:contributors license=MIT -->

Published under the [MIT](https://github.com/unjs/rc9/blob/main/LICENSE) license.
Made by [community](https://github.com/unjs/rc9/graphs/contributors) 💛
<br><br>
<a href="https://github.com/unjs/rc9/graphs/contributors">
<img src="https://contrib.rocks/image?repo=unjs/rc9" />
</a>

<!-- /automd -->

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