@cagov/11ty-build-system

CaGov's 11ty Build System

Adds CSS, Javascript, and other pre-processing powers to your 11ty build.

No need to worry about setting up long, multi-step npm scripts. Say goodbye to task runners. Let go of your attachment to bespoke watchers. We'll take care of the details.

🚧 Work in progress! Use at your peril! 🚧

Note: this plugin only works correctly with newer 1.0.0-beta versions of 11ty.

Installation

First, install this plugin into your 11ty project.

npm install @cagov/11ty-build-system

Next, drop the plugin into your .eleventy.js file.

const cagovBuildSystem = require('@cagov/11ty-build-system');

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(cagovBuildSystem, {
    // Your buildConfig options go here, see below.
  });

  // ...the rest of your project's 11ty config code...
};

TL;DR: here's an example of the plugin's options.

const cagovBuildSystem = require('@cagov/11ty-build-system');

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(cagovBuildSystem, {
    postcss: {
      file: 'src/css/postcss.config.js',
      watch: ['src/css/**/*']
    },
    rollup: {
      file: 'src/js/rollup.config.js',
      watch: ['src/js/**/*']
    },
    beforeBuild: () => {
      // Download files, check APIs, etc.
    }
  });

  // ...the rest of your project's 11ty config code...
};

PostCSS Configuration

For your CSS needs, this plugin picks up PostCSS files.

The following example will process a single postcss.config.js file in the src/css folder of your project.

eleventyConfig.addPlugin(cagovBuildSystem, {
  postcss: {
    file: 'src/css/postcss.config.js',
    watch: ['src/css/**/*']
  }
});

If needed, you may process multiple PostCSS config files. Just supply an array of configurations.

eleventyConfig.addPlugin(cagovBuildSystem, {
  postcss: [
    {
      file: 'src/css/postcss.home.config.js',
      watch: ['src/css/home/**/*']
    },
    {
      file: 'src/css/postcss.page.config.js',
      watch: [
        'src/css/page/**/*',
        'src/css/page-widget/**/*'
      ]
    }
  ]
});

Each PostCSS configuration supplied to the plugin accepts the following options.

Name	Description
file	Path to the `postcss.config.js' file.
watch	An array of glob expressions to watch for changes within 11ty's serve mode.

PostCSS Files

Here's an example postcss.config.js file for use alongside the above PostCSS configuration.

const purgecss = require('@fullhuman/postcss-purgecss');
const cssnano = require('cssnano');
const { purgeCssDefaults } = require('@cagov/11ty-build-system/src/postcss.js');

module.exports = {
  to: 'pages/_buildoutput/built.css',
  from: 'docs/css/build/development.css',
  plugins: [
    purgecss({
      content: [
          'pages/**/*.njk',
          'pages/**/*.html',
          'pages/**/*.js',
          'pages/wordpress-posts/banner*.html',
          'pages/@(translated|wordpress)-posts/new*.html'
      ],
      ...purgeCssDefaults
    }),
    cssnano
  ]
};

PostCSS config files should include the following required fields.

Name	Description
to	Path to the destination CSS file.
from	Path to the source CSS (or Sass) file.
plugins	An array of PostCSS plugins.

You may also set map, parser, syntax, and/or stringifier options as described in the PostCSS docs.

Rollup Configuration

For Javascript processing, this plugin provides Rollup.

The following example will process a single rollup.config.js file.

eleventyConfig.addPlugin(cagovBuildSystem, {
  rollup: {
    file: 'src/js/rollup.config.js',
    watch: ['src/js/**/*']
  }
});

Like PostCSS, you may specify multiple Rollup configurations in an array.

eleventyConfig.addPlugin(cagovBuildSystem, {
  rollup: [
    {
      file: 'src/js/rollup.es5.config.js',
      watch: ['src/js/polyfills/**/*']
    },
    {
      file: 'src/js/rollup.all.config.js',
      watch: ['src/js/**/*']
    }
  ]
});

Note the options for Rollup configs.

Name	Description
file	Path to the `rollup.config.js' file.
watch	An array of glob expressions to watch for changes within 11ty's serve mode.

Rollup Files

Here's an example rollup.config.js file.

import resolve from '@rollup/plugin-node-resolve';
import { terser } from 'rollup-plugin-terser';

export default {
  input: 'src/js/index.js',
  output: {
    file: 'dist/js/bundle.js',
    format: 'esm'
  },
  plugins: [resolve(), terser()]
};

Check the Rollup documentation for more details.

Sass Configuration

For Sass processing, this plugin provides Dart Sass.

eleventyConfig.addPlugin(cagovBuildSystem, {
  sass: {
    watch: ['src/css/**/*'],
    output: 'docs/css/build/development.css',
    options: {
      file: 'src/css/index.scss',
      includePaths: [ 'src/css' ]
    },
    postcss: {
      file: 'src/css/postcss.built.config.js'
    }
  }
});

Like PostCSS and Rollup, you may opt to include multiple Sass configurations via array.

Sass configuration options follow.

Name	Description
output	Destination file path for Sass output.
watch	An array of glob expressions to watch for changes within 11ty's serve mode.
options	Processing options to pass to Dart Sass. See the Sass JS API documentation for a full list of options.
options.file	Path to the source Sass file. See Sass JS API documentation for more info.
postcss	A PostCSS configuration for post-processing the Sass output.

Run your own code

The plugin provides a beforeBuild callback function. You may use this to run any code before the 11ty build.

eleventyConfig.addPlugin(cagovBuildSystem, {
  beforeBuild: () => {
    // Download files, check APIs, etc.
  },
});

Order of operations

1. The beforeBuild callback runs first.
2. Next, postcss and rollup configurations run in parallel.
3. Finally, 11ty performs the rest of its usual build.

Running the build

Because this is an 11ty plugin, no special npm scripts are needed. Just use standard 11ty CLI commands.

# Build
eleventy

# Build in dev mode
NODE_ENV=development eleventy

# Serve and watch in dev mode
NODE_ENV=development eleventy --serve --incremental