Little bundles of code, little bundles of joy.
Create minimal per-page or app-level bundles of CSS, JavaScript, or HTML bundles to be included in your Eleventy project.
Makes implementing Critical CSS, per-page in-use-only CSS/JS bundles, SVG icon libraries, secondary HTML content to load via XHR.
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, {
// Folder (in the output directory) bundle files will write to:
toFileDirectory: "bundle",
// Default bundle types
bundles: ["css", "js", "html"],
// Shortcode names
shortcodes: {
get: "getBundle",
toFile: "getBundleFileUrl",
// override bundle add names:
add: {
// use `addCss` instead of `css`
// css: "addCss"
}
}
});
};The following shortcodes are included in this plugin:
css,js, andhtmlto add code to a bundle.getBundleandgetBundleFileUrlto get bundled code.
# 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!
<!-- Use this *anywhere*: a layout file, content template, etc -->
<style>{% getBundle "css" %}</style>
<!--
You can add more code to the bundle after calling
getBundle and it will be included.
-->
{% css %}* { color: orange; }{% endcss %}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" %}"><!-- This goes into a `defer` bucket (the bucket can be any string value) -->
{% css "defer" %}em { font-style: italic; }{% endcss %}<!-- Pass the arbitrary `defer` bucket name as an additional argument -->
<style>{% getBundle "css", "defer" %}</style>
<link rel="stylesheet" href="{% getBundleFileUrl 'css', 'defer' %}">A default bucket is implied:
<!-- These two statements are the same -->
{% css %}em { font-style: italic; }{% endcss %}
{% css "default" %}em { font-style: italic; }{% endcss %}
<!-- These two are the same too -->
<style>{% getBundle "css" %}</style>
<style>{% getBundle "css", "default" %}</style>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>
<!-- Inlined critical styles -->
<style>{% getBundle "css" %}</style>
<!-- Deferred non-critical styles -->
<link rel="stylesheet" href="{% getBundleFileUrl 'css', 'defer' %}" media="print" onload="this.media='all'">
<noscript>
<link rel="stylesheet" href="{% getBundleFileUrl 'css', 'defer' %}">
</noscript>
</head>
<body>
<!-- This goes into a `default` bucket -->
{% css %}/* Inline in the head, great with @font-face! */{% endcss %}
<!-- This goes into a `defer` bucket (the bucket can be any string value) -->
{% css "defer" %}/* Load me later */{% endcss %}
</body>
<!-- … -->Related:
- Check out the demo of Critical CSS using Eleventy Edge for a repeat view optimization without JavaScript.
- You may want to improve the above code with
fetchprioritywhen browser support improves.
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>
<!-- And anywhere on your page you can add icons to the set -->
{% 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>TODO
TODO
htmlbundles are not allowed to reference other bundles in content (yet). If this will be useful to you, please file an issue!
If you’d like to add your own bundle types (in addition to css, js, and html), you can do so:
const bundlerPlugin = require("@11ty/eleventy-plugin-bundle");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(bundlerPlugin, {
bundles: ["css", "js", "html", "mine"]
});
};You could remove existing bundle types too, the bundles array content is not deeply merged. The addition of "mine" in this array:
- creates a new
mineshortcode for adding arbitrary code to this bundle - adds
"mine"as an eligible type argument togetBundleandgetBundleFileUrl
