A Productive Aurelia 2 Build Setup

When starting a new Aurelia 2 project I have a few “musts” that I always setup. These Build Setup tweaks are adding functionality as well as quality of life things. 👨‍🏭

My preferred setup for my Aurelia 2 projects are based on the Dumber bundler. The build config is setup in gulp, and easily configurable without proprietary tool knowledge. Ok – I admit, some gulp knowledge helps 😂

My standard project setup options look like follows:

• Bundler – Dumber
• Transpiler – TypeScript
• Shadow DOM or CSS Modules – No (varies depending on app)
• CSS Processor – Plain CSS
• Unit Testing Framework – Jest
• E2E Tests – Cypress
• Sample Project – With Direct Routing (varies depending on app)

If preferred, this exact same project setup can be created in silent mode like this:
npx makes aurelia new-project-name -s dumber,typescript,cypress,app-with-router

🎁 Additions

After setting up a new project, my tweaks and additions are:

1. Add a resources folder to hold images, json files etc
2. Tweak glob pattern for other files that trigger rebuilds in watch mode
3. Add PurgeCSS and add it to the gulp buildCSS function

📂 A Folder for Images, Config Files Etc.

I add a folder in the root next to src named resources. In this folder I store pretty much everything that is not code or markup.

Since I store config files and such in here that changes how the app behaves, I also add this folder to the gulp watch glob. This enables changes to files in the folder to trigger new builds when developing in watch-mode.

Modify gulpfile.js and add a glob pattern, se below.

function watch() {
  return gulp.watch(["src/**/*", "resources/**/*"], gulp.series(build, reload));
}

👀 Another File to Add to the Watch Glob

Another file I end up modifying, at least in the beginning of every project, is the _index.html template. Might as well add it to the watch glob! 😁

function watch() {
  return gulp.watch(["src/**/*", "resources/**/*", "_index.html"], gulp.series(build, reload));
}

🧹 Add PurgeCSS to the Build Setup

A great tool for removing obsolete CSS is PurgeCSS. If you are using any third party styling frameworks like Bootstrap, TailwindCSS or something else, you are shipping loads of unused styles to your app visitors. PurgeCSS will help you remove all those unused styles 🥳

Even if it’s a small project and you write all your CSS yourself, it’s easy to miss something and let some dead CSS slip through the cracks every now and then 😵

Install PurgeCSS using npm
npm i -D gulp-purgecss

Then modify the buildCSS() function in the gulpfile.js like this👇

// add this at the top of the file
const purgecss = require("gulp-purgecss");

// then we add PurgeCSS to the CSS build
function buildCss(src) {
  return gulp
    .src(src, { sourcemaps: !isProduction })
    .pipe(
      // add PurgeCSS to remove unused CSS
      purgecss({
        content: ["src/**/*.html", "_index.html"],
        whitelist: ["goto-active"],
      })
    )
    .pipe(
      postcss([
        autoprefixer(),
        // use postcss-url to inline any image/font/svg.
        // postcss-url by default use base64 for images, but
        // encodeURIComponent for svg which does NOT work on
        // some browsers.
        // Here we enforce base64 encoding for all assets to
        // improve compatibility on svg.
        postcssUrl({ url: "inline", encodeType: "base64" }),
      ])
    );
}

Notice we need to add goto-active to the whitelist, as it’s a dynamic class put on navigation elements by the router, and otherwise that class will be removed.

🔮 Conclusion

Having a good DEV environment setup is key for a good flow and productivity. Make sure to think about the build setup as a part of that too! Don’t stay complacent when you feel pain points – modify, tweak and improve! 🥽

Do you have any great productivity or functionality adding tweaks?
Comment below and share your best tips! 🤗

🔗 Resources

Example code can be found on GitHub
Dumber docs
PurgeCSS home
Using VS Code to stamp out Aurelia components
Read more about Aurelia 2 on the docs site

Happy Coding! 😊