New Features and Upgrade Considerations for Eleventy v2.0.0

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.

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.

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:

• Introduction to WebC
• Understanding WebC Features and Concepts

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.

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.

• Regular ignore management
• Watch ignore management

Various enhancements landed for incremental builds, notably:

• Layouts - a change rebuilds any templates using that layout
• Collections - adding or deleting a tag from a template will rebuild any related templates

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:

• dir - object with current project directories
• outputMode - default is fs (file system), or option passed via —to
• runMode - one of build, watch, or serve
• results - for eleventy.after only, includes processed Eleventy output

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

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).

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:

• declaring collections for incremental builds to trigger rebuilds when a collection item is changed
• new/updated data structure for collection items, notably:
  • Use page.url instead of url (see docs for other properties moved to page)
  • Use content instead of data.templateContent to get the compiled output

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.

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

• new date option: git Created
• pagination option to allow empty pages when no data is available
• map one URL to multiple files, useful for scenarios like internationalization
• Markdown processing by default now has disabled indented code blocks

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
---

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

• changing collection data references like url to be based off of page and updating templateContent to content
• including the file extension when you define a layout, ex layout: base.njk instead of layout: base

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

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

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:

• On-demand builders which cache the result after the first page request (rebuild to expire), great for infrequently used pages or generating open graph images
• Dynamic templates which re-render on every page request, great for CMS previews, accepting user input, or even to generate and display site search results

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

• slug filter changed to slugify with better special character handling
• Date formats are assumed to be UTC
• Noted earlier, but configuration events to run code before or after compile
• Data deep merge on by default resulting in data like tags that are added in a template and a layout being merged together, rather than the template, which has higher data cascade priority, having only its tags used
• Speaking of the data cascade, the priority of front matter data in layouts was lowered
• Global data was allowed to be added from the config file
• Custom template extensions allow adding your own template formats and provide a custom compiler, such as the docs example of adding Sass processing
• The render plugin enables shortcodes to render template strings or files inside of a template of a different template language, ex. render a Markdown block within Nunjucks

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.