Skip to content

New Features and Upgrade Considerations for Eleventy v2.0.0

Posted on: Jan 12, 2023 by Stephanie Eckles
🍿 6 min. read

Review major feature additions, breaking changes, and various enhancements to prepare for the v2 stable release of 11ty.

2.0.0 canaries have been available for quite some time, and creator Zach Leatherman has helpfully been updating the docs by adding labels to note when a feature became available.

The 2.0.0 release is available as of February 8, 2023, which includes the changes noted in this article.

Recently, I set out to create a new Eleventy project for the first time in a few months using the latest Canary and hit some unexpected errors. That led me down the rabbit hole to see what exactly had changed so I could be prepared to update projects, especially as I use similar setups cross-project and maintain a few 11ty starters.

This may not be 100% comprehensive, but it includes the most impactful highlights for general use of 11ty.

If it’s been a while since you created or updated an Eleventy project, you may want to glance at the last section for features you might have missed from v1.0.0.

Major Feature Additions

Eleventy Edge

Currently only available for projects run on Netlify, this exciting addition brings a shortcode that allows dynamic content to be added to your projects on the edge. What’s that, you say? It means you can modify a page request before the page content is sent to the user, which allows getting data like the user’s timezone. It also enables retrieving cookies to check if the user is authenticated and permitted to access a particular route. Or, it offers the chance to set cookies to persist preferences like a color theme. These ideas are just the beginning of what’s possible with Eleventy Edge!

Join me on January 25 and 26 for TheJam.dev where I’ll demonstrate using Eleventy Edge to build a membership site on Eleventy.

WebC

In line with moves made by other site builders, WebC offers the ability for single-file web components. Really what that means is WebC is a first-class templating language in Eleventy that you can use to render “real” web components or as an alternative to solutions like Nunjucks includes and macros for reusable components in your 11ty site.

Check out these posts from 11ty Rocks to learn more about WebC use cases and features:

Breaking Changes

A few changes as noted in the release notes, which Zach recommends using the eleventy-upgrade-helper plugin to discover whether your site is impacted.

Update from an earlier version of this post: a proposed breaking change to addPassthroughCopy was reversed.

Configuration, Build, and Serve

First up, there are now new options for naming your Eleventy config file.

  1. .eleventy.js - only option < v2.0.0-canary.15
  2. eleventy.config.js - coming in v2
  3. eleventy.config.cjs - coming in v2

The default Eleventy dev server is now a custom solution instead of BrowserSync. If you have customizations reliant on BrowserSync, you can revert back with a config option. However, the default server is much faster and lighter and doesn’t require loading any JS during watch and serve local dev.

If your site benefits from programmatic ignores (like separating dev vs. prod environment files), you may be interested to know that --watch ignores are now available separately.

Various enhancements landed for incremental builds, notably:

To make local dev even faster, you may wish to opt-in to emulated passthrough file copying for faster local builds. Note that opting-in may have breaking behavior if you are copying through files that other processes depend on. For instance, maybe you are referencing a file for your serverless build or a plugin requires a precise and real file path from your final output. In that case, simply do not opt-in to this feature.

A new command line flag of --ignore-initial will run Eleventy without an initial build.

The configuration events added in v1 will have event arguments available in v2 that provide metadata about the build, including the following objects:

Finally, for configuration updates, if you don’t want directory indexes created by default, you can change your default permalinks with this snippet.

Custom Data and Data Cascade

The supplied data variables of eleventy (added in v1) and page will be available as of v2 in filters and shortcodes. The page variable has also been extended to transforms, linters, and collection entries.

I’m a big fan of directory data files (here are some tips for using them). In v2, you can configure a different base file name for them instead of the default of matching them to the directory file name, ex. index.

Custom data formats (the ability to support additional template extensions) received various updates.

A late addition for Eleventy Serverless (introduced v1) added the ability to compile the data cascade. This means access to collections without extra hoops to make them available to serverless templates (with caveats noted in docs).

Collections, Filters, and Shortcodes

An exciting update for those of us who have tried to get dynamic/real-time data pulled at build-time is universal async shortcodes and universal async filters!

Collections received a couple of updates, including:

You can now chain ‘log’ in filters, for example {{ myData | log | otherFilter }}. Whereas before, you would have to break those calls apart, now log will output and then pass the data along the chain to the next filter.

Content Creation

Here are some quick hits that may impact how you create content with Eleventy:

Also, when defining layout files, it is now strongly recommended to include the layout file extension. This is due to the slowness of determining which file is actually meant to be used when no extension is included.

---
layout: base <- no longer recommended
layout: base.njk <- best practice: always add file extension
---

Upgrading to v2.0.0

The top two things that may impact your current projects are:

And, perhaps you may want to change the name of your Eleventy config.

There's also an upgrade plugin available: eleventy-upgrade-help

What You Missed From v1.0.0

I started using Eleventy at version 0.10.0 in April 2020, and v1.0.0 stable was released a year and a half later, on January 9, 2022. If you also did most of your learning with Eleventy before v1 and haven’t updated things or built new in a while, there’s a good chance you missed some of the following!

Probably the biggest feature splash was Eleventy Serverless, which enables building entire templates upon page request for fully dynamic pages. The two available modes are:

Here are several other key updates from Eleventy v1.0.0:


Whew, that was a lot! Go forth and enjoy building with these new and updated Eleventy features! PS - if you're new to Eleventy, check out my guide to creating your first basic 11ty website.