eleventy-plugin-bundle
Little bundles of code, little bundles of joy.
Create minimal per-page or app-level bundles of CSS, JavaScript, or HTML to be included in your Eleventy project.
Makes it easy to implement Critical CSS, in-use-only CSS/JS bundles, SVG icon libraries, or secondary HTML content to load via XHR.
Why?
This project is a minimum-viable-bundler and asset pipeline in Eleventy. It does not perform any transpilation or code manipulation (by default). The code you put in is the code you get out (with configurable transforms
if you’d like to modify the code).
For more larger, more complex use cases you may want to use a more full featured bundler like Vite, Parcel, Webpack, rollup, esbuild, or others.
But do note that a full-featured bundler has a significant build performance cost, so take care to weigh the cost of using that style of bundler against whether or not this plugin has sufficient functionality for your use case—especially as the platform matures and we see diminishing returns on code transpilation (ES modules everywhere).
Installation
It’s available on npm as @11ty/eleventy-plugin-bundle
:
npm install @11ty/eleventy-plugin-bundle
And then in your Eleventy configuration file (probably .eleventy.js
):
const bundlerPlugin = require("@11ty/eleventy-plugin-bundle");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(bundlerPlugin);
};
Full options list
And then in your Eleventy configuration file (probably .eleventy.js
):
const bundlerPlugin = require("@11ty/eleventy-plugin-bundle");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(bundlerPlugin, {
toFileDirectory: "bundle",
bundles: [],
transforms: [],
hoistDuplicateBundlesFor: [],
});
};
Read more about hoistDuplicateBundlesFor
and duplicate bundle hoisting.
Usage
The following Universal Shortcodes (available in njk
, liquid
, hbs
, 11ty.js
, and webc
) are provided by this plugin:
css
, js
, and html
to add code to a bundle.getBundle
and getBundleFileUrl
to get bundled code.
Here’s a real-world commit showing this in use on the eleventy-base-blog
project.
Add bundle code in a Markdown file in Eleventy
# My Blog Post
This is some content, I am writing markup.
{% css %}
em { font-style: italic; }
{% endcss %}
## More Markdown
{% css %}
strong { font-weight: bold; }
{% endcss %}
Renders to:
<h1>My Blog Post</h1>
<p>This is some content, I am writing markup.</p>
<h2>More Markdown</h2>
Note that the bundled code is excluded!
Render bundle code
<style>{% getBundle "css" %}</style>
{% css %}* { color: orange; }{% endcss %}
Write a bundle to a file
Writes the bundle content to a content-hashed file location in your output directory and returns the URL to the file for use like this:
<link rel="stylesheet" href="{% getBundleFileUrl "css" %}">
Asset bucketing
{% css "defer" %}em { font-style: italic; }{% endcss %}
<style>{% getBundle "css", "defer" %}</style>
<link rel="stylesheet" href="{% getBundleFileUrl 'css', 'defer' %}">
A default
bucket is implied:
{% css %}em { font-style: italic; }{% endcss %}
{% css "default" %}em { font-style: italic; }{% endcss %}
<style>{% getBundle "css" %}</style>
<style>{% getBundle "css", "default" %}</style>
Examples
Critical CSS
Use asset bucketing to divide CSS between the default
bucket and a defer
bucket, loaded asynchronously.
(Note that some HTML boilerplate has been omitted from the sample below)
<head>
<style>{% getBundle "css" %}</style>
<link rel="stylesheet" href="{% getBundleFileUrl 'css', 'defer' %}" media="print" onload="this.media='all'">
<noscript>
<link rel="stylesheet" href="{% getBundleFileUrl 'css', 'defer' %}">
</noscript>
</head>
<body>
{% css %}/* Inline in the head, great with @font-face! */{% endcss %}
{% css "defer" %}/* Load me later */{% endcss %}
</body>
Related:
SVG Icon Library
Here svg
is an asset bucket on the html
bundle.
<svg width="0" height="0" aria-hidden="true" style="position: absolute;">
<defs>{% getBundle "html", "svg" %}</defs>
</svg>
{% html "svg" %}
<g id="icon-close"><path d="…" /></g>
{% endhtml %}
And now you can use `icon-close` in as many SVG instances as you’d like (without repeating the heftier SVG content).
<svg><use xlink:href="#icon-close"></use></svg>
<svg><use xlink:href="#icon-close"></use></svg>
<svg><use xlink:href="#icon-close"></use></svg>
<svg><use xlink:href="#icon-close"></use></svg>
React Helmet-style <head>
additions
This might exist in an Eleventy layout file:
<head>
{% getBundle "html", "head" %}
</head>
And then in your content you might want to page-specific preconnect
:
{% html "head" %}
<link href="https://v1.opengraph.11ty.dev" rel="preconnect" crossorigin>
{% endhtml %}
Bundle Sass with the Render Plugin
You can render template syntax inside of the {% css %}
shortcode too, if you’d like to do more advanced things using Eleventy template types.
This example assumes you have added the Render plugin and the scss
custom template type to your Eleventy configuration file.
{% css %}
{% renderTemplate "scss" %}
h1 { .test { color: red; } }
{% endrenderTemplate %}
{% endcss %}
Now the compiled Sass is available in your default bundle and will show up in getBundle
and getBundleFileUrl
.
Use with WebC
Starting with @11ty/eleventy-plugin-webc@0.9.0
(track at issue #48) this plugin is used by default in the Eleventy WebC plugin. Specifically, WebC Bundler Mode now uses the bundle plugin under the hood.
To add CSS to a bundle in WebC, you would use a <style>
element in a WebC page or component:
<style></style>
<style webc:keep></style>
To add JS to a page bundle in WebC, you would use a <script>
element in a WebC page or component:
<script></script>
<script webc:keep></script>
- Existing calls via WebC helpers
getCss
or getJs
(e.g. <style @raw="getCss(page.url)">
) have been wired up to getBundle
(for "css"
and "js"
respectively) automatically.
- For consistency, you may prefer using the bundle plugin method names everywhere:
<style @raw="getBundle('css')">
and <script @raw="getBundle('js')">
both work fine.
- Outside of WebC, the Universal Filters
webcGetCss
and webcGetJs
were available to access CSS and JS bundles but are considered deprecated in favor of the getBundle
Universal Shortcode ({% getBundle "css" %}
and {% getBundle "js" %}
respectively).
Modify the bundle output
You can wire up your own async-friendly callbacks to transform the bundle output too. Here’s a quick example of postcss
integration.
const bundlerPlugin = require("@11ty/eleventy-plugin-bundle");
const postcss = require("postcss");
const postcssNested = require("postcss-nested");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(bundlerPlugin, {
transforms: [
async function(content) {
let result = await postcss([postcssNested]).process(content, { from: this.page.inputPath, to: null });
return result.css;
}
]
});
};
Bundling on the Edge
Coming soon
Advanced options:
Add your own bundle type
If you’d like to add your own bundle types (in addition to the guaranteed types: css
, js
, and html
), you can do so:
const bundlerPlugin = require("@11ty/eleventy-plugin-bundle");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(bundlerPlugin, {
bundles: ["possum"]
});
};
This does two things:
- creates a new
possum
shortcode for adding arbitrary code to this bundle - adds
"possum"
as an eligible type argument to getBundle
and getBundleFileUrl
Limitations
Bundles do not support nesting or recursion (yet?). If this will be useful to you, please file an issue!