Information for: DEVELOPERS   PARTNERS

Front-end development and Acquia BLT

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.

Acquia 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. Additionally, Acquia BLT ships with Cog, a base theme that provides front end dependencies and front end build tasks compatible with Acquia BLT.

Available target hooks

By default, Acquia 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, Acquia 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'

If you are using a sub-theme of Cog, executing npm install in your theme directory will install all dependencies listed in package.json.

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 Acquia 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, Acquia 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'

If you are using a sub-theme of Cog, executing npm run build in your theme directory will execute the command defined in scripts.build in package.json.

Test

During the execution of blt tests, Acquia 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'

If you are using a sub-theme of Cog, executing npm test in your theme directory will execute the command defined in scripts.test in package.json.

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, Acquia BLT does not have any system requirements for front-end commands, as Acquia BLT does not provide any front-end commands itself. Remember that Acquia 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).