# iso-conf

> Simple config handling with Standard Schema validation and extended JSON serialization

Latest version **0.4.2** (published 2026-10-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install iso-conf
pnpm add iso-conf
yarn add iso-conf
bun add iso-conf
```

## Health

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

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

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2026-10-02 |
| First published | 2026-05-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 58.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Hugo Dias <hugomrdias@gmail.com> (hugodias.me) |
| Maintainers | hugomrdias |
| Keywords | config, conf, settings, storage, standard-schema |

## Links

- npm: https://www.npmjs.com/package/iso-conf
- Repository: hugomrdias/iso-repo
- Homepage: https://github.com/hugomrdias/iso-repo/tree/master/packages/iso-conf
- Issues: https://github.com/hugomrdias/iso-repo/issues
- npm.io page: https://npm.io/package/iso-conf

## Dependencies (5)

- [dot-prop](https://npm.io/package/dot-prop.md) ^10.2.0
- [iso-base](https://npm.io/package/iso-base.md) ^4.4.0
- [env-paths](https://npm.io/package/env-paths.md) ^4.0.0
- [@standard-schema/spec](https://npm.io/package/@standard-schema/spec.md) ^1.1.0
- [@standard-schema/utils](https://npm.io/package/@standard-schema/utils.md) ^0.3.0

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.4.2 (latest) — 2026-10-02
- 0.4.1 — 2026-09-27
- 0.4.0 — 2026-06-15
- 0.3.0 — 2026-06-15
- 0.2.0 — 2026-05-29
- 0.1.0 — 2026-05-29

## README

# iso-conf [![NPM Version](https://img.shields.io/npm/v/iso-conf.svg)](https://www.npmjs.com/package/iso-conf) [![License](https://img.shields.io/npm/l/iso-conf.svg)](https://github.com/hugomrdias/iso-repo/blob/main/license) [![iso-conf](https://github.com/hugomrdias/iso-repo/actions/workflows/iso-conf.yml/badge.svg)](https://github.com/hugomrdias/iso-repo/actions/workflows/iso-conf.yml)

> Simple config handling for your app or module with [Standard Schema](https://standardschema.dev) validation and extended JSON serialization

## Features

- Fully typed via [Standard Schema](https://standardschema.dev) — works with Zod, Valibot, ArkType, and more
- Extended JSON types (URL, Map, Set, bigint, RegExp, Uint8Array)
- Atomic writes to disk
- Dot-notation access for nested properties
- Change hooks (`onDidChange`, `onDidAnyChange`)
- Defaults from schema

## Install

```bash
pnpm install iso-conf
```

## Usage

```js
import { z } from 'zod/v4'
import { Conf } from 'iso-conf'

const schema = z.object({
  foo: z.number().min(1).max(100).default(50),
  bar: z.url().optional(),
})

const config = new Conf({ projectName: 'my-app', schema })

config.set('foo', 42)
console.log(config.get('foo'))
//=> 42
```

Any [Standard Schema](https://standardschema.dev) compliant library can be used for the `schema` option. Zod is shown above as an example only.

### Defaults and required fields

Missing top-level keys are filled from the `defaults` option and then from schema defaults, on every read and write. `defaults` is required when the schema has required fields without a schema default, since a fresh config would otherwise fail validation.

```js
const schema = z.object({
  token: z.string(),
  retries: z.number().default(3),
})

const config = new Conf({ projectName: 'my-app', schema, defaults: { token: '' } })

config.reset('token') // => ''
config.clear() // => { token: '', retries: 3 }
```

The schema output is what gets written to disk and validated again on the next read, so it must also be valid schema input. Transforms that change a value's type (e.g. `z.string().transform((s) => s.length)`) are rejected on write.

## Docs

Check <https://hugomrdias.github.io/iso-repo/modules/iso_conf.html>

## License

MIT © [Hugo Dias](http://hugodias.me)

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