The Equal Justice Initiative
Eleventy
The possum is Eleventy’s mascot
Eleventy Blog
Menu
Eleventy 1.93s
Astro 22.90s

Calling all courageous canary testers for Eleventy v3.0

2023 December 17
Subscribe to the Eleventy News Feed

Are you feeling adventurous? A few short days ago we released the first alpha release of Eleventy v3.0 on the canary channel. If you’d like to try it out, use the following command to install it in your project:

npm install @11ty/eleventy@canary --save-exact

We recommend using --save-exact with the canary channel so you always get the exact same version every time. This will add something like "@11ty/eleventy": "3.0.0-alpha.2" to your package.json instead of "^3.0.0-alpha.2" (the carat is basically shorthand for: “give me the newest 3.0.x release”).

Rest assured, these releases have now been well-tested in production: both https://www.zachleat.com/ and https://www.11ty.dev/ are now using 3.0 alpha releases.

Thank You Jump to heading

This release would not have been possible without the support of IndieWeb Avatar for https://cloudcannon.com/eleventy-cms/?utm_campaign=11ty-partner&utm_source=official-sponsorCloudCannon.

I’ve been working with the incredible folks at CloudCannon for a few months now and have grown to love their git-backed CMS product. It works great with your existing deployment workflow: you don’t need to change frameworks or hosts, just add web-based editing! The site mounting feature has been incredible for my development velocity.

Screenshot of https://cloudcannon.com/eleventy-cms/?utm_campaign=11ty-partner&utm_source=official-sponsor

New features and a short upgrade guide Jump to heading

The flagship feature for this release is our first-class bundler-free (read: it’s fast) ESM support. Practically speaking, this means you can add "type": "module" to your package.json and all of the Node *.js files in your project will now expect ESM syntax (e.g. import instead of require).

ESM is not required. Your existing CommonJS (CJS) projects (known for use of module.exports and require) will still work great with Eleventy 3.0 and we will continue to support CommonJS in Eleventy moving forward.

You have two upgrade path options (pick which one suits your project best):

  1. Leave your existing Eleventy project as CommonJS. This is the easiest migration path. Use of require for I18nPlugin, RenderPlugin, or HTMLBasePlugin will need to be updated.
  2. Make your project ESM-first. This is highly recommended for new projects and is the best way to write JavaScript moving forward. 11ty-website went all in on ESM but (as a reminder) ESM is not required and a project-wide upgrade to ESM isn’t necessary either. You can add "type": "module" to your package.json and rename your Node .js files to .cjs and be done with it. Later on, you can slowly upgrade to ESM syntax one JavaScript file at a time by renaming back from .cjs to .js.

Upgrade examples Jump to heading

You can check out these two pull requests showing how these large-ish web site codebases were converted to use Eleventy v3.0:

How to require("@11ty/eleventy") in CommonJS Jump to heading

This step is only necessary if you use CommonJS for your Eleventy configuration file (e.g. .eleventy.js or eleventy.config.js or eleventy.config.cjs).

If you use the I18nPlugin, RenderPlugin, or HTMLBasePlugin, you will need to make the following change in your CommonJS config file:

// Any combination of these
const { I18nPlugin, RenderPlugin, HtmlBasePlugin } = require("@11ty/eleventy");

module.exports = function(eleventyConfig) {
// …
};

If you’re continuing to use CommonJS, these will need to be updated to dynamic imports instead (you can’t require an ESM package but you can use await import() in CommonJS to work around it):

// Eleventy 3.0 supports async configuration callbacks:
module.exports = async function(eleventyConfig) {
// Any combination of these
const { I18nPlugin, RenderPlugin, HtmlBasePlugin } = await import("@11ty/eleventy");

// …
};

‼️ Warning ‼️ Project Slipstream Changes Jump to heading

Per feedback from our community survey we’re making a few big changes in Eleventy v3.0 we’re referring to as Project Slipstream.

If you’re interested in the unique benefits of the Jamstack and want to learn more, join us at thefutureofjamstack.org:

Screenshot of https://thefutureofjamstack.org/

What’s next? Jump to heading

Our little project had a few set-backs this year but now we’re running on all cylinders now and it’s full steam ahead.

We’ll likely spend a few months doing active development on v3.0: taking feedback, bug fixing, and iterating on a few new surprises too. You can follow along with this progress on the GitHub milestone.

We’ll be talking about it all on Mastodon—make sure to follow along:


Read more blog posts: Jump to heading