cleaner-config

Cleaner Config

A utility to easily manage strongly-typed JSON configs using cleaners for runtime type-checking. The benefits for using type-checked config:

• Clear error messages
• Easy to refactor your config
• Always valid default/sample config

Usage

Installation

yarn add cleaner-config

config.ts

Your config is completely managed by a cleaner (asConfig). All you need is a file for your config cleaner and config object returned by makeConfig.

import { makeConfig } from 'cleaner-config'
import { asObject, asOptional, asString } from 'cleaners'

export const asConfig = asObject({
  username: asOptional(asString),
  password: asOptional(asString),
})

export const config = makeConfig(asConfig)

index.ts

Now you can use this type information to make a config object from the JSON config file.

import { config } from './config'

// config is ready to use...

API

function makeConfig(asConfig: Cleaner<T>, filepath?: string): T

The makeConfig utility function will read the config.json relative to process.cwd() and type-check the JSON at runtime using the asConfig cleaner argument.

An optional filepath argument can be passed to makeConfig to customize the config file path. The path is relative to current working directory. The path is treated as absolute if prefixed with a forward-slash (/).

makeConfig(asConfig, 'custom-config.json')
makeConfig(asConfig, '/etc/config.json')
makeConfig(asConfig, process.env.CONFIG)

Default Config

Providing a default config (i.e sample, example) is trivial using cleaners. When a config file is not found, the return value of your asConfig cleaner is used as the default config as long as it doesn't throw given {} as the input.

export const asConfig = asObject({
  username: asOptional(asString, 'john'),
  password: asOptional(asString, 'supersecret'),
})

export const config = makeConfig(asConfig)

The config.json file will automatically be created with the default values if it doesn't exist. This means zero-configuration for your app out of the box!

With a cleaner config, you no longer need to copying config.sample.json to config.json! This is automated for you. This saves you a step when running your app and also the overhead of maintaining an a default config file that isn't type checked.

Configure Script

Although the makeConfig function will create a new config JSON file at app runtime, we can do better. We can add a configure script in our package.json and include this in the prepare life-cycle script.

{
  "scripts": {
    "configure": "node -r sucrase/register src/config.ts",
    "prepare": "yarn configure && yarn build"
  }
}

Now our config file is available after app installation, ready for modification!

CLI

Conveniently, cleaner-config comes with a configure CLI utility which can be used instead of a script in your package.json.

{
  "scripts": {
    "prepare": "configure && yarn build"
  }
}

The configure will look for a config.ts file in your project root or in src/, compile it using sucrase, and then run it using node. Optionally, you can provide a file path argument to your config script.

configure src/my-config.ts

Changelog

0.1.10 (2023-10-19)

• fixed: configure CLI runs the config file using node -r sucrase/register for proper module resolution handling.