Skip to main content

bud.config

Creating a config file is the standard way of interfacing with bud.js.

  • The file name should include bud in the name.
  • The module should be located in the project root, .config or config directory
  • The module can be written in JavaScript, TypeScript, YML or JSON5.
  • JavaScript and TypeScript configurations can either export a configuration function or import bud and use it directly.

Example configurations​

bud.config.ts
import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.entry(`app`, [`app.js`, `app.css`])
}

Importing bud.js directly​

You can import bud.js directly and use it in your configuration.

import {bud} from '@roots/bud'

bud.entry(`app`, [`app.js`, `app.css`])

Using multiple configuration files​

It is possible to create more than one bud.js configuration file.

When more than one configuration file is present they are execuetd in the following order:

  1. bud.* - the standard, base configuration.
  2. bud.local.* - local configuration.
  3. bud.{production,development}.* - mode specific configuration. Applied when bud.mode matches.
  4. bud.{production,development}.local.* - mode specific local configuration. Applied when bud.mode matches.

You may want to add bud.local.* to your .gitignore file. This way contributors to your project can make specific overrides using bud.local.* files without affecting the base configuration kept in source control.

Configuring bud.js with JSON and YML​

Each key is a reference to a bud.js call. The supplied values are the arguments to that call, expressed as an array.

Calling functions​

For example, the following bud.js configuration:

entry:
  - app
  - app.js

is equivalent to:

bud.entry('app', 'app.js')

There is some flexibility here if you are passing a single value and it is NOT an array. So, this is okay:

entry:
  app: app.js

Since it can easily be interpreted by bud.js as:

entry:
  - app: app.js

Which is equivalent to a single item in array of arguments, containing an object.

bud.entry({app: 'app.js'})

Conversely, since bud.assets expects an array, the following yml would cause an error:

# This is incorrect
assets: ['src/**/*.html', 'app/**/*.html']

How is bud.js to know whether you intended to pass multiple parameters or a single array? It can't, and so this is the result:

bud.assets('src/**/*.html', 'app/**/*.html') // wrong
// what we wanted: bud.assets(['src/**/*.html', 'app/**/*.html'])

To fix it, we must remember that we are passing an array of the function parameters, and wrap our argument in an array:

assets:
  - ['src/**/*.html', 'app/**/*.html']

Accessing nested values​

You can access nested properties with standard yml indentation:

babel:
  setPluginOptions:
    - '@babel/plugin-transform-runtime'
    - {helpers: true}

You can also use dot notation:

babel.setPluginOptions:
  - '@babel/plugin-transform-runtime'
  - {helpers: true}

Accessing bud values​

You can make reference to the bud object with _bud.

splitChunks: _bud.isProduction

You can tap bud with an arrow fn if needed. These functions will be called as they are encountered and supplied with the bud.js instance.

minimize: bud => bud.isProduction

This is the equivalent of:

bud.tap('minimize', bud.isProduction)

Treating a value as a function​

If you need to execute some code but don't need the bud object, you can prefix a string with => to indicate that it should be treated as a function. These functions will be called as they are encountered.

This will log 4:

log: => 2 + 2

Handling callbacks​

Some functions accept functions as a value. In cases like these wrap the function in an additional => so that the config parser does not call the function itself.

webpackConfig: >
  => config => ({...config, parallelism: 1})

bud.tap and bud.tapAsync can be helpful for dynamic configuration and work like this:

tap: >
  => bud => {
    // this is a very flexible
    // area to do all sorts of dynamic config stuff
    bud.log('hi!')
  }

tapAsync: >
  => async bud => {
    // same as above but async
    bud.log('hi!', '...eventually')
  }

If you're doing a lot of this remember that you can create JS configurations in addition to the yml one.

Configuring bud.js with JSON​

You can use JSON5 syntax, similar to what is supported in tsconfig.json.

{
  /** Comments are fine */
  entry: ["app", ["app.js"]],
  runtime: true,
  copyDir: "assets",
  babel: {
    setPluginOptions: [
      "@babel/plugin-transform-runtime",
      {helpers: false, regenerator: false}
    ]
  }
}

If you are doing a lot of dynamic configuration you may find it easier to use YML or JS. Ultimately, it's your choice, but we recommend using yml over json for more complicated configs.