JSON configuration example

Build now recommends build.ini, but JSON remains fully supported.

The JSON format represents the same ideas with nested objects:

• the top-level keys are glob patterns
• each task may contain name, require, and execute
• execute contains command and arguments

Example build.json

{
	"script/**/*.es6": {
		"name": "Bundle JavaScript",
		"require": {
			"node_modules/.bin/esbuild": ">=0.17",
			"node": ">=18"
		},
		"execute": {
			"command": "./node_modules/.bin/esbuild",
			"arguments": [
				"./script/app.es6",
				"--bundle",
				"--sourcemap",
				"--outfile=./www/script.js"
			]
		}
	},
	"style/**/*.scss": {
		"name": "Compile Sass",
		"require": {
			"sass": ">=1.6"
		},
		"execute": {
			"command": "sass",
			"arguments": [
				"./style/style.scss",
				"./www/style.css"
			]
		}
	},
	"asset/**/*": {
		"name": "Publish static assets",
		"require": {
			"vendor/bin/sync": "^1.3"
		},
		"execute": {
			"command": "vendor/bin/sync",
			"arguments": [
				"./asset",
				"./www/asset",
				"--symlink"
			]
		}
	}
}

JSON and INI side by side

The same JavaScript task written in INI looks like this:

[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

The behaviour is the same. The choice is mainly about which format fits the project better.

Mode files in JSON

Mode files work in exactly the same way as with INI.

Base file:

build.json

{
	"script/**/*.es6": {
		"name": "Bundle JavaScript",
		"execute": {
			"command": "./node_modules/.bin/esbuild",
			"arguments": ["./script/app.es6", "--bundle", "--sourcemap", "--outfile=./www/script.js"]
		}
	}
}

Override file:

build.production.json

{
	"script/**/*.es6": {
		"name": "Bundle JavaScript for production",
		"execute": {
			"arguments": ["./script/app.es6", "--bundle", "--minify", "--outfile=./www/script.js"]
		}
	}
}

When we run vendor/bin/build --mode production, Build merges the two objects and keeps any properties not overridden by the mode file.