Little bundles of code, little bundles of joy.
npm install @11ty/eleventy-plugin-bundleLittle 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.
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).
No installation necessary. Starting with Eleventy v3.0.0-alpha.10 and newer, this plugin is now bundled with Eleventy.
By default, Bundle Plugin v2.0 does not include any default bundles. You must add these yourself via eleventyConfig.addBundle. One notable exception happens when using the WebC Eleventy Plugin, which adds css, js, and html bundles for you.
To create a bundle type, use eleventyConfig.addBundle in your Eleventy configuration file (default .eleventy.js):
``js`
// .eleventy.js
export default function(eleventyConfig) {
eleventyConfig.addBundle("css");
};
This does two things:
1. Creates a new css shortcode for adding arbitrary code to this bundle"css"
2. Adds as an eligible type argument to the getBundle and getBundleFileUrl shortcodes.
`js
export default function(eleventyConfig) {
eleventyConfig.addBundle("css", {
// (Optional) Folder (relative to output directory) files will write to
toFileDirectory: "bundle",
// (Optional) File extension used for bundle file output, defaults to bundle name
outputFileExtension: "css",
// (Optional) Name of shortcode for use in templates, defaults to bundle name
shortcodeName: "css",
// shortcodeName: false, // disable this feature.
// (Optional) Modify bundle content
transforms: [],
// (Optional) If two identical code blocks exist in non-default buckets, they’ll be hoisted to the first bucket in common.
hoist: true,
// (Optional) In 11ty.js templates, having a named export of bundle will populate your bundles.`
bundleExportKey: "bundle",
// bundleExportKey: false, // disable this feature.
});
};
Read more about hoist and duplicate bundle hoisting.
The following Universal Shortcodes (available in njk, liquid, hbs, 11ty.js, and webc) are provided by this plugin:
* getBundle to retrieve bundled code as a string.getBundleFileUrl
* to create a bundle file on disk and retrieve the URL to that file.
Here’s a real-world commit showing this in use on the eleventy-base-blog project.
`mdMy Blog Post
This is some content, I am writing markup.
{% css %}
em { font-style: italic; }
{% endcss %}
{% css %}
strong { font-weight: bold; }
{% endcss %}
`
Renders to:
`htmlMy Blog Post
This is some content, I am writing markup.
Note that the bundled code is excluded!
_There are a few more examples below!_
$3
`html
{% css %}* { color: orange; }{% endcss %}
`$3
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:
`html
`Note that writing bundles to files will likely be slower for empty-cache first time visitors but better cached in the browser for repeat-views (and across multiple pages, too).
$3
`html
{% css "defer" %}em { font-style: italic; }{% endcss %}
``html
`A
default bucket is implied:`html
{% css %}em { font-style: italic; }{% endcss %}
{% css "default" %}em { font-style: italic; }{% endcss %}
`$3
#### Critical CSS
`js
// .eleventy.js
export default function(eleventyConfig) {
eleventyConfig.addBundle("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)_
`html
{% css %}/ Inline in the head, great with @font-face! /{% endcss %}
{% css "defer" %}/ Load me later /{% endcss %}
`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
fetchpriority when browser support improves.#### SVG Icon Library
Here an
svg is bundle is created.`js
// .eleventy.js
export default function(eleventyConfig) {
eleventyConfig.addBundle("svg");
};
``html
{% svg %}
{% endsvg %}
And now you can use
icon-close in as many SVG instances as you’d like (without repeating the heftier SVG content).
`#### React Helmet-style
additions`js
// .eleventy.js
export default function(eleventyConfig) {
eleventyConfig.addBundle("html");
};
`This might exist in an Eleventy layout file:
`html
{% getBundle "html", "head" %}
`And then in your content you might want to page-specific
preconnect:`html
{% html "head" %}
{% 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.`html
{% 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
To add JS to a page bundle in WebC, you would use a
* Existing calls via WebC helpers
getCss or getJs (e.g. alert(1);` to alert twice?