Different environments

Having a single file to define all of your client-side build requirements has limitations when different environments are used. For example, when deploying your project to production, you may want to have a different build step for a particular task, such as compiling JavaScript without dev tools like source maps.

Build modes

The base build configuration for the library utilises a configuration file named build.json. However, the build process is flexible and allows for custom configurations tailored to different build modes.

These specialised configurations are called build modes and take the form of files such as build.development.json and build.production.json. These files provide the ability to override the build process according to the specific needs of a given environment or mode.

The name of the build mode is always appended to the file's name, between the basename and the extension.

To run a specific build mode, specify its name using the --mode parameter, or -m short parameter.

Example production build override

Take this base build.json file that has three different task blocks. It acts as the base configuration for any other modes specified.

build.json:

{
	"script/**/*.es6": {
		"name": "ES6 compilation with source maps",
		"require": {
			"node": "*",
			"./node_modules/.bin/esbuild": ">=0.17.12"
		},
		"execute": {
			"command": "./node_modules/.bin/esbuild",
			"arguments": ["script/script.es6", "--bundle", "--sourcemap", "--outfile=www/script.js", "--loader:.es6=js"]
		}
	},

	"style/**/*.scss": {
		"require": {
			"sass": ">=1.6"
		},
		"execute": {
			"command": "/usr/local/bin/sass",
			"arguments": ["./style/style.scss", "www/style.css"]
		}
	},

	"asset/**/*": {
		"require": {
			"vendor/bin/sync": ">=1.3.0"
		},
		"execute": {
			"command": "vendor/bin/sync",
			"arguments": ["./asset", "./www/asset", "--symlink"]
		}
	}
}

In production, the ES6 compilation stage should have different execution arguments. Rather than supplying the whole configuration again, only the task blocks that are different need to be defined in the mode file.

build.production.json:

{
	"script/**/*.es6": {
		"name": "ES6 production compilation",
		"execute": {
			"arguments": ["script/script.es6", "--bundle", "--outfile=www/script.js", "--loader:.es6=js", "--target=chrome105,firefox105,edge105,safari15"]
		}
	}
}

Notice how there is only one task block, and within that task block, only the properties that need changing have been specified.

Running build --mode production will execute all of the base build.json task blocks, with the modified ES6 production compilation execution arguments.

---

Next, check out how default config can be used across multiple projects.