Installing client side packages

Starting a new project should not mean hunting down every build tool by hand. If our project has a package.json, Build can get its client-side packages ready before running the build tasks.

Getting started

We need Node.js and npm installed first. The project's package.json describes the packages it needs, such as webpack, Sass, or esbuild.

From the project directory, we can run the usual command:

vendor/bin/build

In WebEngine applications, we can use gt build instead.

Build checks the installed packages against package.json. If a required package is missing, or its installed version does not satisfy the declared version, we will see:

Client-side packages are missing or do not match package.json, running `npm install`...

Build then runs npm install --include=dev in the working directory and shows npm's progress in the terminal. Development dependencies are included because this is where projects commonly keep their build tools. This also applies when we use --mode production.

Once installation succeeds, Build checks the packages again before checking task requirements and running the build. If the packages already match, it skips installation.

Using the installed tools

Build adds the project's node_modules/.bin to the front of PATH for requirement checks and task execution. We can therefore use names such as webpack, sass, or esbuild in our configuration without installing those commands globally.

For example:

[style/**/*.scss]
name=Compile Sass
require=sass >=1.6
execute=sass ./style/style.scss ./www/style.css

The same behaviour applies to build.json. Explicit paths such as ./node_modules/.bin/sass still work.

If something goes wrong

If npm is missing, Build shows a link to the Node.js and npm installation guide.

If installation fails, or the packages still do not match afterwards, Build stops before running the tasks. We can read npm's output, fix the reported problem, and try again. To run the installation ourselves, use:

npm install --include=dev

Missing build commands, such as webpack, also come with links to the Node.js setup guide and npm's package installation documentation. If a command is still missing after installation, check that its package is declared in package.json and that the command name is correct.

What Build checks

Build uses npm ls --json --depth=0 --include=dev to check direct dependencies. It checks the installed packages, rather than keeping a record of whether npm install has been run before. Extra installed packages alone do not trigger installation, and this check does not validate every dependency of a dependency or compare the installation against a lockfile.

The working directory is normally the directory we run Build from. If we pass a file to --config, Build uses that file's directory; if we pass a directory, it uses that directory. This is where it looks for package.json and runs npm, even when the build configuration comes from --default.

In watch mode, the package check happens once at startup. Restart Build after changing package.json to run the check again.

Projects without a package.json continue to use their chosen tools without invoking npm.

---

See build tasks for more examples of configuring commands and requirements.