Eleventy v3.0.0: Possums ❤️ ESM (2024-10-01)
We did it. After 22 pre-releases and over a year of work, Eleventy 3.0.0 is now available. You can try it out now on your project using:
```js
npm install @11ty/eleventy@latest
```
**If you’re upgrading from a previous version** of Eleventy, use the [Upgrade Help plugin](https://v3.11ty.dev/docs/plugins/upgrade-help/) for automated checks and help with your upgrade!
**[Why should you use Eleventy?](https://v3.11ty.dev/#why-should-you-use-eleventy)** Eleventy is a flexible and production-ready site generator known for its zero-client JavaScript footprint, [speedy sites, speedy builds](https://v3.11ty.dev/docs/performance/), and [full control over the output](https://www.youtube.com/watch?v=b4frtsT4Cgo).
A few numbers on the best version of Eleventy yet:
| Stats | `v2.0.1` | `v3.0.0` |
| - | - | - |
| 20% smaller | 35.2 MB | 28.1 MB |
| 11% fewer dependencies | 213 | 189 |
| 9% faster npm install | 4.511s\* | 4.103s\* |
_\*fastest time of 3 runs (bypassing local cache)_
## Flagship 3.0 features
1. Eleventy is now written in ESM with **full** support for ESM in your projects: configuration, data files, 11ty.js templates, etc. For many projects this won’t be a breaking change and we’ll continue to support CommonJS too. Every example on the docs now includes both a CommonJS and ESM version. Docs: https://v3.11ty.dev/docs/cjs-esm/
```js
// ESM
export default function(eleventyConfig) {}
// We’ll keep supporting CommonJS:
module.exports = function(eleventyConfig) {}
```
2. Supporting more package managers and runtimes: pnpm, yarn, Deno. More examples on the docs! https://v3.11ty.dev/docs/
3. Asynchronous configuration #614 Docs: https://v3.11ty.dev/docs/config/
```js
// ESM
export default async function(eleventyConfig) {}
// CommonJS
module.exports = async function(eleventyConfig) {}
```
4. For-free performance improvement to built-in `slugify`, `inputPathToUrl` universal filters (via memoization) #840 Docs: https://v3.11ty.dev/docs/memoize/
5. Named `config` export improves consistency for plugins #3246 and `set*Directory` configuration API methods #1503 Docs: https://v3.11ty.dev/docs/config-shapes/#optional-export-config-object and https://v3.11ty.dev/docs/config/#configuration-options
```js
export default function(eleventyConfig) {
eleventyConfig.setInputDirectory(".");
eleventyConfig.setOutputDirectory("_site");
};
export const config = {
dir: {
input: ".",
output: "_site"
},
};
```
6. Virtual Templates, configuration API to add content (great for plugins, used by the new RSS plugin!) #1612 Docs: https://v3.11ty.dev/docs/virtual-templates/
```js
export default function(eleventyConfig) {
eleventyConfig.addTemplate("robots.njk", "User-agent: *\nAllow: /", {
permalink: "/robots.txt",
});
};
```
7. IdAttribute plugin adds `id` attributes to headings for on-page anchor links (supports all template-languages) #3363 Docs: https://v3.11ty.dev/docs/plugins/id-attribute/
```html
Welcome to my web site
becomes Welcome to my web site
```
8. Plain-text Bundler included: https://v3.11ty.dev/docs/plugins/bundle/
```js
export default function(eleventyConfig) {
eleventyConfig.addBundle("css"); // Adds {% css %} paired shortcode to create per-page CSS bundles
};
```
9. InputPath to URL plugin lets you link directly to an input file path (and we’ll output the right URL) Docs: https://www.11ty.dev/docs/plugins/inputpath-to-url/
```html
Home becomes Home
```
10. Use arbitrary JavaScript with the `js` Front Matter #2819 Docs: https://v3.11ty.dev/docs/data-frontmatter/#javascript-front-matter
```js
---js
const hello = "hi";
---
{{ hello }}
```
11. `page.rawInput` unlocks access to raw template content #1206 https://v3.11ty.dev/docs/data-eleventy-supplied/#page-variable
12. `addPreprocessor` configuration API to modify raw content before rendering works for file ignores and drafts #188 Docs: https://v3.11ty.dev/docs/config-preprocessors/
13. `addDateParsing` configuration API to add your own custom date parsing logic #867 Docs: https://v3.11ty.dev/docs/dates/#configuration-api-for-custom-date-parsing
14. `eleventyDataSchema` data option to validate data cascade values #879 Docs: https://v3.11ty.dev/docs/data-validate/
15. Reserved Eleventy properties in data cascade are now frozen #1173 Docs: https://v3.11ty.dev/docs/data-eleventy-supplied/#frozen-data
16. Support for asynchronous plugins and async-friendly `addPlugin` configuration API #2675 Docs: https://v3.11ty.dev/docs/plugins/#plugins-are-configuration
17. `useLayouts` option for Custom Template Languages allows opt-out of Eleventy Layouts #2830 Docs: https://v3.11ty.dev/docs/languages/custom/#uselayouts
18. `renderTransforms` Universal Filter will run project transforms on an arbitrary block of content (useful for RSS and other feeds) #3294
19. `--incremental=filename.md` on the command line #3324 Docs: https://v3.11ty.dev/docs/usage/#incremental-for-partial-incremental-builds
20. `renderContent` Universal Filter now included with Render Plugin #3370 Docs: https://v3.11ty.dev/docs/plugins/render/#rendercontent-filter
21. Dev Server updates including [`onRequest` API for handling requests dynamically during development](https://github.com/11ty/eleventy-dev-server/releases/tag/v2.0.0) (used with the new [Image Transform plugin](https://v3.11ty.dev/docs/plugins/image/#eleventy-transform))
## Breaking Changes and Upgrade Path
**Rather than navigating this list manually, use the [Upgrade Help plugin](https://v3.11ty.dev/docs/plugins/upgrade-help/) for automated project checks and upgrade help!**
* Requires Node 18 or newer.
* Removes Serverless and Edge plugins.
* Use of bundled Eleventy plugins from CommonJS requires changing `require("@11ty/eleventy")` to `await import("@11ty/eleventy")` for ESM reasons. We provide [helpful error messaging for this](https://www.zachleat.com/web/future-friendly-esm/).
* `pug`, `ejs`, `haml`, `mustache`, and `handlebars` template languages moved from core to official plugins:
* `handlebars`: https://v3.11ty.dev/docs/languages/handlebars/
* `mustache`: https://v3.11ty.dev/docs/languages/mustache/
* `ejs`: https://v3.11ty.dev/docs/languages/ejs/
* `haml`: https://v3.11ty.dev/docs/languages/haml/
* `pug`: https://v3.11ty.dev/docs/languages/pug/
* Throw errors if `--config=` command line file is missing #3373
* The `htmlOutputSuffix` feature was removed #3327
* Aliased custom templates must be declared in active formats #3302
* `--formats=` and `--formats=""` on command line means no formats (previously aliased to `*`) #3255
* Custom Template Language `compileOptions.permalink` option changed from `true` to `"raw"` #2780
* Major semver updates of dependencies:
* `js-yaml` [v3 to v4 Changelog](https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md#400---2021-01-03)
* Better error messaging when using tabs in YAML
* Numbers are now parsed according to YAML 1.2 spec (from 1.1)
* `@sindresorhus/slugify` [v2 to v3 Changelog](https://github.com/sindresorhus/slugify/releases/tag/v2.0.0): Node 12+, Pure ESM
* `bcp-47-normalize` [v1 to v2 Changelog](https://github.com/wooorm/bcp-47-normalize/releases/tag/2.0.0): Pure ESM
* `dependency-graph` [v0.x to v1 Changelog](https://github.com/jriecken/dependency-graph/blob/master/CHANGELOG.md#100-dec-5-2023)
* `iso-639-1` [v2 to v3 Changelog](https://github.com/meikidd/iso-639-1/blob/master/CHANGELOG.md#v300): Pure ESM
* `markdown-it` [v13 to v14 Changelog](https://github.com/markdown-it/markdown-it/blob/master/CHANGELOG.md#1400---2023-12-08): Pure ESM, removed `dist` folder
* [Full list of breaking changes](https://github.com/11ty/eleventy/issues?q=milestone%3A%22Eleventy+3.0.0%22+is%3Aclosed+label%3Abreaking-change)
## Minutiae
* Packages are now published using [npm package provenance](https://github.blog/security/supply-chain-security/introducing-npm-package-provenance/).
* The code base is using tabs 😱😈 #3098
**Full Eleventy v3 Milestone** (177 closed): https://github.com/11ty/eleventy/milestone/40?closed=1
**Full Changelog**: https://github.com/11ty/eleventy/compare/v2.0.1...v3.0.0
## Thank You Notes
This release would not have been possible without our community and supporters.
* To everyone that has built something with Eleventy: thank you!
* To everyone that has answered a question about Eleventy: on the Discord, on social media, in GitHub issues or discussion, at your local meetup or coffee shop: thank you!
* To everyone that attended the [11ty Conference](https://conf.11ty.dev/) earlier this year: thank you!
* To everyone that brought a well-intentioned complaint about something you didn’t like about Eleventy: thank you!
* To everyone that dropped a few nice words of appreciation: **_thank you!_**
* To everyone that has supported us and made this release possible: **_thank you!_**
Thank you to @bobmonsour, @pdehaan, @Snapstromegon, @cdransf, @5t3ph, @BenDMyers, @siakaramalegos, @shivjm, @dleatherman, @darthmall, @clottman, @nachtfunke, @David-Large, Olivia Nicholson, and @mneumegen for their community contributions!
Thank you for the code contributions from @VividVisions, @mayank99, @Zearin, @chriskirknielsen, @mendhak, @fqueze, @shivjm, @rdela, @w0whitaker, @vrugtehagel, @sachac, @Snapstromegon, @alifeee, @uncenter, @Zwyx, @mayankkamboj47, @aschrab, @jgarber623, @korverdev, @mathertel, @mathieuprog, @epelc, @Ryuno-Ki, @lexoyo, @satgo1546, @KiwiKilian