npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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

  1. The beforeBuild callback runs first.
  2. Next, all asset processors 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