Skip to content

CSS and JS (Webpack)

For compiling front-end assets (CSS and Javascript), we are utilizing Webpack. In order to run Webpack, first follow the instructions in the Software setup page page to make sure you have NodeJS installed and are using the appropriate version as detailed in the .nvmrc file.

Once you have confirmed you have NodeJS installed, navigate to the root directory of the bs-theme-www folder and make sure all Node packages are installed by running:

npm install

Building assets

To build CSS and JS assets, run the following command from the bs-theme-www directory:

npm run build

The build script will run an intial build of the CSS and JS files and will enter watch mode, meaning that any CSS or JS files that are changed will trigger a rebuild of the assets.

Source files

All of the CSS and JS source files can be found in /assets/src/sass and /assets/src/js respectively. If you need to modify or add CSS / JS, do it in those files. If you need to add a new file, follow the steps below based on whether you're adding CSS or JS

Warning

Note that the watch functionality of Webpack when running the npm run build command does not watch for new files, only changes to existing files. This means that if you add a new file, you'll need to stop Webpack (hit Ctrl+c on the terminal window running Webpack) and then relaunch Webpack with npm run build.

Adding new CSS file(s)

The entry point for Webpack when compiling the SASS files into CSS is /assets/src/sass/main.scss. You can add new SASS files anywhere under /assets/src/sass and as long as the file is @imported into the main.scss file at some point, Webpack will pick it up and compile it into the final CSS bundle.

Adding new JS file(s)

Adding JS files works a little differently. This is because we are concatenating all the JS files into a single file to work around some JsonP encapsulation errors that Webpack introduces. What all this means is that there is no single entry point for JS, so you will have to add your new JS file to the Webpack manifest before it gets included in the bundle. Once you have created your new file, open /assets/webpack.config.js and register your new file in the correct place. The line of code to register the file will look something like the following:

path.resolve(__dirname, 'src/js/my-file.js'),
Note that there are two places in the Webpack where this type of registration happens for Javascript files. Depending on what type of file you're adding, change the place you register the file as follows:

  • if you are adding a new vendor JS file (i.e. a third-party plugin), add the file itself in the /assets/src/js/lib folder and register the file in the Vendor JS section of the Webpack config file.
  • if you are adding a custom written JS file, add the file directly to /assets/src/js and register it in the Application JS section of the Webpack config file.

Output files

When Webpack compiles the SASS and JS files, it will result in the final bundles being produced in the /assets/dist directory. There should be three files produced:

  • The combined CSS file
  • The combined Vendor JS file
  • The combined Application JS file

Note

The files above are the production files for CSS and JS and are used both in local development and for the live site(s). As such, when changes are made, the compiled files in /assets/dist should be committed to Git along with the source files.

All of the files will also contain a content hash in the filename, meaning the filename will look something like this: vendor.9bb1cd483394903fde15961fbb507b6d.js. The content hash is there for cache-busting to ensure that if changes are made to the file, the browser will load the new file rather than relying on the old cached version.

Warning

The content hash is automatically generated for the CSS file and the Application JS file. However, it cannot currently be created automatically for the Vendor JS file. If you make changes to the vendor bundle (such as updating a vendor JS file to a new version or adding a new vendor JS file), you'll need to manually update the content hash to something new in the webpack.config.js file.

Find the line that looks something like this: 

dest: path.resolve(__dirname, 'dist/vendor.9bb1cd483394903fde15961fbb507b6d.js'),

and update the content hash (9bb1cd483394903fde15961fbb507b6d in this example) to something new

Embedding files in the site

Embedding the production CSS and JS files into the site is handled automatically (as long as you follow the instructions on this page). The scripts will be embedded via the /includes/assets.php file at runtime. For more information, consult the assets.php section of the Functions page.