@roots/bud

• Overview
• Installation
• Getting started
  • Running a build
  • Configuration API
• Extensions
• Documentation

Overview

A webpack framework combining the best parts of Laravel Mix and Symfony Encore.

Installation

There is a recommended preset available to make it as easy as possible to get started:

yarn add @roots/bud-preset-recommend --dev

To get started without the preset you'll want to install both @roots/bud and @roots/bud-cli:

yarn add @roots/bud @roots/bud-cli --dev

Getting started

Bud centers around a configuration file situated in the root of the project. By default this file should be named bud.config.js.

You can use the CLI to generate a starter configuration file, if you need a jumping off point:

yarn bud publish @roots/bud-support bud.config.js

Dead simple bud.config.js example:

const { bud } = require("@roots/bud");

bud.entry("app", ["app.js"]).run();

The framework can do many more things. But, one of Bud's flagpole axioms is that more is not always better for many common use cases. In fact, just using entry and run you can already compile project files. For many people this may very well be enough.

A more advanced configuration might look like this:

const { bud } = require("@roots/bud");

/**
 * Extend bud with additional functionality
 */
bud.use([
  require("@roots/bud-babel"),
  require("@roots/bud-postcss"),
  require("@roots/bud-react"),
]);

/**
 * Create a dynamic link library for fast compilation
 * of the react runtime.
 */
bud.library(["react", "react-dom"]);

/**
 * Compile two separate sets of files.
 */
bud.entry({ app: ["app.{js,css}"] });

/**
 * When building for production, minify assets.
 * When in development, use verbose source-maps.
 */
bud.when(
  bud.isProduction,
  (bud) => bud.minify(),
  (bud) => bud.devtool("eval-source-map")
);

/**
 * Run the build and cache the results for
 * faster rebuilds when modules are unchanged.
 */
bud.run();

Example implementations

There are example implementations available for reference in /examples.

Running a build

Once you've set up your configuration file the following command will run the build:

yarn bud build

You should see your built assets in the dist directory of your project.

Running in production mode

yarn bud build --mode production

Running in development mode

yarn bud build --mode development

Configuration API

The following is a (hopefully) exhaustive list of the utilities designed to make setting up your build as easy as possible.

This isn't the last word on what is possible with Bud, just a collection of functions intended to simplify common developer needs/wants to as great a degree as possible. There are many valid ways to interact with Bud that utilize none of these functions.

Extending

Bud, by itself, provides an intentionally sparse set of features.

In fact, much of the core of Bud is actually made up of extensions. This is to make it easy for developers and extension authors to swap out parts of the framework as needed.

Suffice to say, extensibility is a fundamental design tenet of Bud as software. You will likely want to utilize extensions in your project.

First-party extensions

There are a number of Roots maintained extensions available to kickstart your projects. For more information on using them refer to the extension's documentation.

Name	Description	Usage	Package
@roots/bud-babel	Babel support.	README ↗
@roots/bud-compress	Gzip/Brotli compression..	README ↗
@roots/bud-emotion	Adds emotion.	README ↗
@roots/bud-entrypoints	Asset manifest.	README ↗
@roots/bud-esbuild	Adds esbuild.	README ↗
@roots/bud-eslint	Adds eslint support.	README ↗
@roots/bud-imagemin	Compress image assets	README ↗
@roots/bud-library	DLL support	README ↗
@roots/bud-mdx	DLL support	README ↗
@roots/bud-postcss	PostCss support.	README ↗
@roots/bud-prettier	Prettier support.	README ↗
@roots/bud-purgecss	PurgeCss support.	README ↗
@roots/bud-react	React support.	README ↗
@roots/bud-sass	Sass support.	README ↗
@roots/bud-stylelint	Stylelint support.	README ↗
@roots/bud-tailwindcss	Tailwindcss support.	README ↗
@roots/bud-terser	Terser support.	README ↗
@roots/bud-typescript	TypeScript support.	README ↗
@roots/bud-vue	Vue framework support.	README ↗
@roots/bud-wordpress-dependencies	WP dependencies.	README ↗
@roots/bud-wordpress-externals	WP externals.	README ↗
@roots/bud-wordpress-manifests	WP asset manifest.	README ↗

Third-party extensions

Have you produced a Bud extension and want to share it here? Please, create an issue sharing information about your project.

Documentation and details

• Documentation index
• Configuration guide
• Setting the compilation mode
• Working with containers
• Working with env values
• Toggling feature flags
• Working with the filesystem
• Using hooks
• Bud CLI

Typescript

Bud is written in TypeScript but supports JS and TS projects. For TS users most project typings can be sourced from @roots/bud-typings.

Contributing

Contributions are welcome from everyone.

We have contributing guidelines to help you get started.

Bud sponsors

Help support our open-source development efforts by becoming a patron.

Community

Keep track of development and community news.

• Participate on the Roots Discourse
• Follow @rootswp on Twitter
• Read and subscribe to the Roots Blog
• Subscribe to the Roots Newsletter
• Listen to the Roots Radio podcast