Parse-Config

• Helper package for parsing / loading config files with .yml and .env extensions
• Includes simple template system for dynamically setting config values
• Now with full TypeScript support and ES modules!

Install

• With pnpm => pnpm add @keg-hub/parse-config
• With yarn => yarn add @keg-hub/parse-config
• With npm => npm install @keg-hub/parse-config

Usage

ES Modules (Recommended)

// Import the entire package
import * as PConf from '@keg-hub/parse-config'
const ymlObj = await PConf.loadYml(...)
const envObj = await PConf.loadEnv(...)
const templateStr = await PConf.fillTemplate(...)

// Import just sections from the package
import { yml, env, template } from '@keg-hub/parse-config'
const ymlObj = await yml.load(...)
const envObj = await env.load(...)
const templateStr = await template.fill(...)

// Import just specific methods from the package (better tree-shaking)
import { loadYml, loadEnv, fillTemplate, loadConfigs } from '@keg-hub/parse-config'
const ymlObj = await loadYml(...)
const envObj = await loadEnv(...)
const templateStr = await fillTemplate(...)
const configObj = loadConfigs(...)

TypeScript

import { loadYml, loadEnv, LoadConfigOptions } from '@keg-hub/parse-config'

// Full type safety and autocomplete
const options: LoadConfigOptions = {
  env: 'production',
  name: 'my-app',
}

const config = loadConfigs(options)

CommonJS (Legacy)

// Import just specific methods from the package
const { loadYml, loadEnv, fillTemplate } = require('@keg-hub/parse-config')
const ymlObj = await loadYml(...)
const envObj = await loadEnv(...)
const templateStr = await fillTemplate(...)

// Load configs based on environment from both .env and .yaml files
const { loadConfigs } = require('@keg-hub/parse-config')
const configObj = loadConfigs(...)

Loading Config Files

• The loadConfigs method can be used to automatically load config files
• The config file names are generated from the passed in options
• All found files are loaded, and merged together as a single config object

Priority

• Priority is based on the name and location of the loaded file
  • The .env, then defaults.env files are always loaded first when noEnv === false, regardless of their location
  • Files loaded last, override previously loaded config values
  • For values files, both yml and yaml extentions are searched for
  • Because yaml is technically the correct extension, it will override the yml counterpart File Name
• Given the following config options
  • env === staging
  • ymlName === values
  • name === app
  • noEnv === false
  • noYml === false
  • ymlPath === env
• Files will be loaded in the following order,
• First .yml files, then .yaml files, and finally .env files. See below example
  • .env then defaults.env ==> Always comes first when noEnv === false
  • values.yml then values.yaml
  • staging.yml then staging.yaml
  • app.yml then app.yaml
  • values_staging.yml then values_staging.yaml
  • values_app.yml then values_app.yaml
  • values_staging_app.yml then values_staging_app.yaml
  • values.staging.yml then values.staging.yaml
  • values.app.yml then values.app.yaml
  • values.staging.app.yml then values.staging.app.yaml
  • values-staging.yml then values-staging.yaml
  • values-app.yml then values-app.yaml
  • values-staging-app.yml then values-staging-app.yaml
  • .env.staging
  • .env.app
  • .env_app_staging
  • .env.app.staging
  • .env.app-staging
  • staging.env
  • app.env
  • app_staging.env
  • app.staging.env
  • app-staging.env

Locations

• After the file names are generated, they are appended to the generated locations
• Some locations are predefined, but custom locations can also be passed via the locations array config option
  • Custom locations are ALWAYS checked after the default locations
  • This allows for any files loaded from the custom locations to override the defaults

loadConfigs - Config Options

import { loadConfigs } from '@keg-hub/parse-config'

const configObj = loadConfigs({
  // Environment prefix of the config files to be loaded ( i.e. `production.env` )
  env: `local`,
  // App prefix of the config files to be loaded ( i.e. `my-app.production.env` )
  name: ``,
  // Should errors be thrown when a file exists but can't be loaded
  error: true,
  // Skip loading .env files
  noEnv: false,
  // Skip loading .yaml files
  noYml: false,
  // The reference name of the values files to be loaded ( i.e. `values.local.yml` )
  ymlName: `values`,
  // Object path to return from loaded yml files
  ymlPath: `env`,
  // Format type the config should be returned as ( object | string )
  format: `object`,
  // Run template replace on the loaded config files
  fill: true,
  // Template data to fill config file with ( Requires the `fill` options value is `true`  )
  data: {...},
  // RegEx pattern when running template replace
  pattern: /{{([^}]*)}}/g,
  // Extra file path and directories to search for config files
  locations: [...],
  // How found configs should be merged. Must be one of overwrite | join | unique.
  mergeStrategy: `overwrite`
})

Tree-Shaking

This package is optimized for tree-shaking. When you import specific functions, bundlers will only include the code you actually use:

// ✅ Good - Only includes loadYml and loadEnv in your bundle
import { loadYml, loadEnv } from '@keg-hub/parse-config'

// ❌ Bad - Includes the entire package
import * as PConf from '@keg-hub/parse-config'

TypeScript Support

This package is written in TypeScript and includes full type definitions. Import types as needed:

import type {
  LoadConfigOptions,
  EnvOptions,
  YmlOptions,
  ParsedContent
} from '@keg-hub/parse-config'