@cagov/11ty-build-system
v1.0.1
Published
An 11ty plugin to implement @cagov's standard build system for 11ty sites.
Downloads
731
Readme
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, {
processors: {
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...
};
Asset Processors
This plugin current supports the following pre-processors for building and bundling your CSS and/or Javascirpt.
Note that you may supply multiple configurations for any of the above processors as an array. For example, both of the PostCSS entries in the following example will be honored.
eleventyConfig.addPlugin(cagovBuildSystem, {
processors: {
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/**/*'
]
}
]
}
});
PostCSS
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, {
processors: {
postcss: {
file: 'src/css/postcss.config.js',
watch: ['src/css/**/*']
}
}
});
PostCSS Configuration 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
For Javascript processing, this plugin provides Rollup.
The following example will process a single rollup.config.js
file.
eleventyConfig.addPlugin(cagovBuildSystem, {
processors: {
rollup: {
file: 'src/js/rollup.config.js',
watch: ['src/js/**/*']
}
}
});
Rollup Configuration Options
|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
For Sass processing, this plugin provides Dart Sass.
eleventyConfig.addPlugin(cagovBuildSystem, {
processors: {
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'
}
}
}
});
Sass Configuration Options
|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.|
Esbuild
The plugin now supports Esbuild.
eleventyConfig.addPlugin(cagovBuildSystem, {
processors: {
esbuild: {
watch: ['src/js/**/*'],
options: {
entryPoints: ['src/js/index.js'],
bundle: true,
minify: true,
outfile: 'dist/js/built.js',
},
}
}
});
Esbuild Configuration Options
|Name|Description|
|:--:|:----------|
|watch
|An array of glob expressions to watch for changes within 11ty's serve mode.|
|options
|Processing options to pass to esbuild. See the esbuild Build API documentation for a full list of options.|
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
- The
beforeBuild
callback runs first. - Next, all asset processors run in parallel.
- 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