Ideally, you will be using a theme that employs SASS or SCSS, a style guide, and other front-end tools that require some type of build process.
Similar to Composer dependencies, your front-end dependencies and compiled front-end assets should not be directly committed to the project repository. Instead, they should be built during the creation of a production-ready artifact.
BLT does not directly manage any of your front-end dependencies or assets, but it does create opportunities for you to hook into the build process with your own custom front-end commands.
Available target hooks
By default, BLT provides an opportunity for your front-end commands to run at the following stages of the build process:
- Install
- Build
- Test
Install
During the execution of blt setup and blt artifact:deploy, BLT will execute command-hooks.frontend-reqs.command. This hook is intended to provide an opportunity to install the tools required for your front-end build process. For instance, you may use this hook to install dependencies using NPM or Bower. For example:
command-hooks:
frontend-reqs:
dir: ${docroot}/themes/custom/[mytheme]
command: 'npm install'
Note
The npm install command does not generally install the same versions of packages from one run to the next, which is undesirable when testing and building for production. If you are deploying front-end assets, you may want to use npm ci instead of npm install to ensure that dependencies are installed consistently and deterministically. If BLT detects that build files (such as package-lock.json) have changed during the build process, it may fail the deployment to prevent untested code from being deployed.
Build
During the execution of blt setup and blt artifact:deploy, BLT will execute command-hooks.frontend-assets.command. This is always executed after command-hooks.frontend-reqs.command. This hook is intended to provide an opportunity to compile your front-end assets, such as compiling SCSS to CSS or generating a style guide.
command-hooks:
frontend-assets:
dir: ${docroot}/themes/custom/mytheme
command: 'npm run build'
Test
During the execution of blt tests, BLT will execute command-hooks.frontend-test.command. This hook is intended to provide an opportunity execute frontend tests, like JavaScript linting and visual regression testing:
command-hooks:
frontend-test:
dir: ${docroot}/themes/custom/mytheme
command: 'npm test'
Executing complex commands
If you need to execute something more complex, you can call a custom script rather than directly embedding your commands in the YAML file, similar to the following:
command-hooks:
frontend-assets:
dir: ${repo.root}
command: ./scripts/custom/my-script.sh
System requirements
Strictly speaking, BLT does not have any system requirements for front-end commands, as BLT does not provide any front-end commands itself. Remember that BLT provides only an opportunity for you to execute your own custom front-end commands. It is your responsibility to determine and install your front-end system requirements, and to ensure that the correct versions of prerequisite tools (including NPM and Bower) are installed wherever you are running deploys (such as locally, in a virtual machine, or in a continuous integration environment).