Stable: 3.0.0
Canary: 3.0.1-alpha.1

Toggle Menu

Eleventy 1.93s

Gatsby 29.05s

Adding CSS, JavaScript, Fonts

There are many paths available to you when you decide you want to start adding assets to an Eleventy project. For most projects, it’s wise to let the project’s complexity and long-term maintenance goals guide which approach you choose. Start simple and grow to the next level in complexity when the project’s requirements necessitate it!

Here are a few options in order from least complex to most complex:

Step 1 Copy CSSWeb FontJavaScript Files

This is the simplest approach and is great for beginners and/or with small projects. It’s great because it doesn’t require a bundler or any external dependencies.

This copies individual CSSJavaScriptWeb Font files that are referenced in your HTMLCSS.

Create a bundle.cssbundle.js file in your root project folder and add some CSSJavaScript code to this file.

Use passthrough file copy to copy the file to the build output folder (you could use a glob here, too):

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("bundle.css");
};

export default function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("font.woff2");
};

export default function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("bundle.js");
};

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("bundle.css");
};

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("font.woff");
};

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("bundle.js");
};

Reference the Web Font file in your CSS using:

@font-face {
	font-family: My Font Name;
	src: url('/font.woff2') format('woff2');
	font-display: swap;
}

Reference the CSS file in your HTML using:

<link rel="stylesheet" href="/bundle.css">

Reference the JavaScript file in your HTML using
```
<script src="/bundle.js"></script>
```

Expand for an example using Concatention, pulling in from CSSJavaScript from multiple sources.

You can use the Nunjucks and Liquid include tag to do simple concatenation.

Next, you can output this code directly to your page:

Filenamepage.njk

<style>
{% include "header.css" %}
{% include "footer.css" %}
{% include "./node_modules/my-ficticious-package-name/package.css" %}
</style>

Filenamepage.njk

<script>
{% include "header.js" %}
{% include "footer.js" %}
{% include "./node_modules/my-ficticious-package-name/package.js" %}
</script>

Step 2 Use an Eleventy Template

You can use an Eleventy Template to generate your bundle file and reference that from your template with <link rel="stylesheet" href="/bundle.css"><script src="/bundle.js"></script>:

Filenamecss-bundle.njk

---
permalink: bundle.css
---
{% include "header.css" %}
{% include "footer.css" %}
{% include "./node_modules/my-ficticious-package-name/package.css" %}

Filenamejs-bundle.njk

---
permalink: bundle.js
---
{% include "header.js" %}
{% include "footer.js" %}
{% include "./node_modules/my-ficticious-package-name/package.js" %}

Expand to see more Quick Tips, showing how to minify this bundle file.

#005—Super Simple CSS Concatenation

Expand to see Community Resources using this approach.

In the article below, Max showcases how to use an styles.11ty.js template file to generate a one-off Sass-compiled stylesheet:

Screenshot of https://mxb.dev/blog/eleventy-asset-pipeline/

Asset Pipelines in Eleventy (2021)

Step 3 Eleventy Custom Templates

You can add js and css (or even scss for Sass) as custom template types in Eleventy. This means that any js and css files added to your project are processed by Eleventy.

This also (optionally) allows you to post-process the CSS (using Sass, PostCSS, or LightningCSS) or client-JavaScript (using esbuild, rollup, WebPack, etc) and write the processed content to your output folder. This also allows you to use features in your bundle code that aren’t available in web browsers, like nesting CSS, TypeScript, or JSX.

Side note: this is strictly for code that runs in a web browser. There is a different approach if you want to use TypeScript or JSX in your Node.js JavaScript files that run as part of your build.

Here are a few great guides to get you started:

Using Eleventy Custom Templates to Add Sass Support to Eleventy

Screenshot of https://pepelsbey.dev/articles/eleventy-css-js/

CSS and JavaScript as First-Class Citizens in Eleventy (esbuild, PostCSS) (2022)

Screenshot of https://11ty.rocks/posts/process-css-with-lightningcss/

Process CSS or Sass with LightningCSS (LightningCSS) (2023)

Step 4 Component-driven Bundles

Eleventy also provides an optional plaintext Bundle plugin that allows you to populate bundles with code from content pages. This allows you to make the CSS and JavaScript content-driven. The bundle plugin can be used in Nunjucks, Liquid, Handlebars, 11ty.js, and WebC templates and is provided for free with the eleventy-base-blog Starter Project.

Furthermore, the bundle plugin is used by WebC to create minimal bundles that are comprised only of CSS and JavaScript from components used on each WebC page. Using WebC in this way provides the best and least-effort investment in the long-term maintenance of a page. When components on the page change, the JavaScript and CSS bundles are automatically streamlined and will not contain extra code from previous designs.

Get started with the Bundle plugin or WebC!