Bunfig

Smart configuration loader for libraries, apps, and CLIs built utilizing Bun.

Features

• 🔄 Smart Config: intelligent configuration loading
• 🌐 Universal: optimized for both Bun & browser environments
• 🪶 Lightweight: zero dependencies, built on native modules
• 💪 Type-Safe: fully typed configurations with generated type definitions
• 🛠️ CLI Tools: powerful & easy-to-use CLI
• 📦 Flexible: supports multiple config file formats (.ts, .js, .mjs, .cjs, .json, .mts, .cts)

Install

bun install -d bunfig

Get Started

If you are building any sort of Bun project, you can use the loadConfig function to load your configuration.

import type { Config } from 'bunfig'
import { loadConfig } from 'bunfig'

interface MyLibraryConfig {
  port: number
  host: string
}

const options: Config<MyLibraryConfig> = {
  name: 'my-app', // required
  cwd: './', // default: process.cwd()
  defaults: { // default: {}
    port: 3000,
    host: 'localhost',
  },
}

const resolvedConfig = await loadConfig(options)

console.log(resolvedConfig) // { port: 3000, host: 'localhost' }, unless a config file is found

Tip

If your process.cwd() includes a $name.config.{ts,js,mjs,cjs,json} (or .$name.config.{ts,js,mjs,cjs,json}) file, it will be loaded and merged with defaults, where file config file values take precedence. For minimalists, it also loads a .$name.{ts,js,mjs,cjs,json} and $name.{ts,js,mjs,cjs,json} file if present.

Alternatively, you can use the config function to load your configuration.

import type { Config } from 'bunfig'
import { config } from 'bunfig'

interface MyAppOrLibraryConfig {
  port: number
  host: string
}

const options: Config<MyAppOrLibraryConfig> = {
  name: 'my-app', // required to know which config file to load
  cwd: './', // default: process.cwd()
  defaults: { // default: {}
    port: 3000,
    host: 'localhost',
  },
}

const resolvedConfig = await config(options)

The config function is a wrapper around the loadConfig function and is useful for loading configuration in a more flexible way. It accepts an options object with the following properties:

• name: The name of the config file to load.
• cwd: The current working directory to load the config file from.
• defaultConfig: The default config to use if no config file is found.
• endpoint: The endpoint to fetch the config from.
• headers: The headers to send to the endpoint.

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please review the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where bunfig is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙