What’s New in Eleventy 2: A Great SSG Just Got Better

Eleventy (or 11ty) is a popular static site generator (SSG) and is regarded as one of the best Node.js options for speed, simplicity, flexibility, and website performance. This tutorial examines version 2.0, released in February 2023.

What is a Static Site Generator?

(If you already use an SSG, please skip ahead …)

You’re probably familiar with WordPress, a content management system (CMS) which powers almost half of all websites. WordPress provides administration panels which allow you to edit and store content in a database. When a user visits a WordPress page, it pulls database content into a template and returns HTML. A simple UI combined with plentiful themes and plugins makes WordPress ideal for clients.

Or does it?

I’m going to make a controversial claim: a CMS is excessive unless you have many authors posting several times daily. WordPress installation is easy and gives non-technical clients a great deal of power. Unfortunately, the long-term cost of managing content, performance, dependencies, and security is often underestimated. Sites can fail because owners break pages, make the site slow, or have their installation hacked.

An SSG does most rendering work once at build time to create a set of static front-end HTML files (with images, CSS, and JavaScript as necessary). It’s more difficult for a client to break something: you can test the resulting pages before deployment, guarantee good performance, and avoid maintaining server-side dependencies such as runtimes or databases. It’s not easy to hack a live static site, because it’s a collection of files. There’s no application to exploit.

An SSG such as Eleventy has a higher up-front cost, because you require development expertise. But long-term maintenance and hosting costs should reduce. You can have the best of both worlds by decoupling the CMS: an SSG builds and deploys a site by pulling content from a client’s privately-hosted content management system.

To read more about the pros and cons of using static site generators, refer to:

• 7 Reasons to Use a Static Site Generator
• 7 Reasons NOT to Use a Static Site Generator

Why Use Eleventy?

Static site generator applications are plentiful, but Eleventy is worth your consideration, because:

• you can build simpler sites without configuration
• you can configure more advanced generation using JavaScript (Node.js) code that’s familiar to web developers
• you can extract content from Markdown files, JSON data, or any API
• you can choose from popular HTML templating engines such as Liquid, Nunjucks, Handlebars, Mustache, EJS, Pug, and more.
• you’re not tied to a JavaScript framework: the resulting site has no JavaScript dependencies unless you intentionally add them
• Eleventy has one of the smallest installation sizes and is faster at rendering than other options

Eleventy 2.0 Improvements and Features

Eleventy 2.0 offers updates and enhancements. Let’s look at some of those now.

A smaller installation size

Version 2.0 requires 32% fewer npm dependencies and reduces the node_module directory weight from 155MB to 34MB. Installation is 30% faster, so deployments to static hosts such as Cloudflare are noticeably faster.

Quicker build time

Eleventy was already fast, but version 2 reduces build times by up to 20%.

Eleventy remains one of the fastest Node.js static site builders, and a large site will typically build 12x quicker than Astro, 15x quicker than Gatsby, and 37x quicker than Next.js. To go faster, you’d need to consider SSGs built using Go, Rust, or C++.

A new (experimental) --incremental flag improves development rendering times further by performing partial builds on pages affected by changes to content or templates.

New development server

A new lightweight and faster development server replaces Browsersync. As before, you start the server with this:

npx eleventy --serve

Then open http://localhost:8080 in your browser. Pages automatically refresh when you make a change to templates, content, CSS, JavaScript, images, or other built assets.

New WebC web components

A new server-side-compatible web component option known as WebC is available. Consider code you create in a webc file:

<!-- sitepoint-link.webc -->
<p><a href="https://www.sitepoint.com/">SitePoint</a></p>

In essence, this is usable in a template using a custom HTML element:

<!-- page.webc -->
<!doctype html>
<html>
  <head>my page</head>
  <body>
    <h1>My page</h1>
    <sitepoint-link></sitepoint-link>
  </body>
</html>

See the WebC documentation for more details and tutorials.

New Render plugin

The Render plugin provides a shortcode which allows you to render a template string inside another template. For example, here’s Markdown inside Liquid:

{% assign title = 'Hello' %}
<h1>{% echo title %}</h1>

{% renderTemplate "md" %}
A new paragraph.

## An H2 sub-title

* list item 1
* list item 2
* list item 3
{% endrenderTemplate %}

New Internationalization plugin

Eleventy 2.0 makes it easier to provide your static site in different languages. This typically means rendering the same page on different URLs for each language:

/about/index.html (default English "About" page)
/es/about/index.html (Spanish "About" page)
/fr/about/index.html (French "About" page)

Then you provide a language choice option in each page’s UI, or redirect server-side after checking the browser’s HTTP Accept-Language request header.

The Internationalization plugin makes this process easier by providing features such as the locale_url filter, which keeps a user on their current language choice. For example:

<a href="{{ "/about/" | locale_url }}">Blog</a>

This renders the URL /es/about/ on Spanish language pages or /fr/about/ on French language pages.

New HTML <base> Plugin

The HTML <base> Plugin provides options allowing you to apply a base path to specific URLs.

New Server Edge Functions

Eleventy 2.0 permits dynamic server-side edge functions to handle logins, personalize content, submit forms, and so on. This is an experimental option limited to Eleventy-supporter Netlify, but support for further static hosts should appear over time.

Start a New Eleventy 2.0 Project

Our Eleventy Guide: A Framework-Agnostic Static Site Generator tutorial provides a step-by-step guide to installing and using the SSG.

The tutorial uses this installation command to install the latest edition of Eleventy:

npm install @11ty/eleventy

You can also use this command to guarantee you install Eleventy 2.0 should a later version be available:

npm install @11ty/eleventy@2

Upgrade an Eleventy 1.0 Site

Most sites should be fine, but be wary of the following version 2.0 breaking changes before you attempt to upgrade a site developed with Eleventy 1.0:

• it requires Node.js 14 or higher (also check your deployment build scripts)
• it installs upgraded template engines
• it disables indented code blocks in Markdown (they can be re-enabled)
• it removes dates from parent directory names
• it preserves periods/dots in global data filenames
• it removes the undocumented renderData feature
• it removes the --passthroughall command-line flag to copy files to the output directory
• it supports default configuration file names of eleventy.config.js and eleventy.config.cjs as well as .eleventy.js
• addShortcode and addFilter now support async functions

The Upgrade Help plugin can spot any potential issues in your site. You can test it with the tutorial code on GitHub.

Assuming you have a working Eleventy 1.0 site, install Eleventy 2.0 and the Upgrade Help plugin from your project directory:

cd my-11ty-site
npm install @11ty/eleventy@2 @11ty/eleventy-upgrade-help@2

Add Upgrade Help as the last plugin in your Eleventy configuration file (named .eleventy.js, eleventy.config.js or eleventy.config.cjs). The example project’s .eleventy.js file starts with this code:

// 11ty configuration
const
  dev = global.dev  = (process.env.ELEVENTY_ENV === 'development'),
  now = new Date();

module.exports = config => {

  /* --- PLUGINS --- */

  // navigation
  config.addPlugin( require('@11ty/eleventy-navigation') );

  /* --- TRANSFORMS -- */

  // inline assets
  config.addTransform('inline', require('./lib/transforms/inline'));

  // etc.

It uses a single @11ty/eleventy-navigation plugin, so add the Upgrade Help plugin line below it:

// 11ty configuration
const
  dev = global.dev  = (process.env.ELEVENTY_ENV === 'development'),
  now = new Date();

module.exports = config => {

  /* --- PLUGINS --- */

  // navigation
  config.addPlugin( require('@11ty/eleventy-navigation') );

  // *** NEW: upgrade help ***
  config.addPlugin( require('@11ty/eleventy-upgrade-help') );

  /* --- TRANSFORMS -- */
  // etc.

Now launch an Eleventy build:

npx eleventy

Your console will show output such as this:

[@11ty/eleventy-upgrade-help] PASSED This project is not using the previously deprecated and disabled by default `dataTemplateEngine` configuration property. Read more at https://www.11ty.dev/docs/data-preprocessing/
[@11ty/eleventy-upgrade-help] PASSED This project is not using the `--passthroughall` command line flag. Read more at https://www.11ty.dev/docs/copy/#passthrough-everything
[@11ty/eleventy-upgrade-help] NOTICE The `liquidjs` dependency was updated from 9.x to 10.x. This should not require action, but you can read the full release notes: https://github.com/harttle/liquidjs/releases/tag/v10.0.0
[@11ty/eleventy-upgrade-help] NOTICE Markdown’s indented code blocks have been disabled by default in 2.0. Unfortunately, this plugin does *NOT* currently test whether this change affects your content. You can re-enable this feature using `eleventyConfig.amendLibrary("md", mdLib => mdLib.enable("code"))`. Read more: https://www.11ty.dev/docs/languages/markdown/#indented-code-blocks
# etc...

Make any required changes and re-run the Eleventy build until all tests show PASSED or NOTICE. Test your site in a variety of browsers using the development web server to ensure it works as expected:

npx eleventy --serve

Once complete, you can remove the Upgrade Help plugin from your Eleventy configuration file:

  // REMOVE: upgrade help
  // config.addPlugin( require('@11ty/eleventy-upgrade-help') );

Uninstall it from your project:

npm uninstall @11ty/eleventy-upgrade-help@2

Finally, update your Git repository or build as necessary.

Summary

Eleventy is one of the best static site generators for Node.js and version 2.0 makes it more appealing. Here’s a summary of why:

• it’s highly configurable and a JavaScript/Node.js base makes life easier for web developers
• documentation is good
• it’s easy to get started, quick to install, and fast to build
• you can use whatever template system you prefer
• it supports basic page features such as navigation, pagination, and dynamic data
• you can back up and version sites using Git or any other source control system
• built sites have no dependency on JavaScript unless you require it
• server-side functionality is possible and improving
• upgrades are painless for most sites (especially compared to other Node.js SSGs I could mention!)
• it’s actively developed and ongoing sponsorship assures long-term support

There are some downsides:

• you require development expertise to get started
• you’re starting with blank HTML: there’s no framework magic
• Eleventy configuration uses CommonJS and doesn’t yet support ES Modules
• Netlify features are good, but there’s no guarantee similar options will arrive for other platforms

For more information, refer to:

• 11ty.dev
• Eleventy v2.0.0, release notes
• Eleventy Guide: A Framework-Agnostic Static Site Generator
• How to Use WordPress as a Headless CMS for Eleventy
• How to Deploy Your Jamstack Site to Cloudflare Pages (Eleventy example provided)