AMP

Introducing the Eleventy AMP Plugin

Websites

I’m happy to introduce the new AMP Plugin for Eleventy. Eleventy is a static site generator offering a simple way to manage your templates and build your site. It works great together with AMP if you want to make your static site more interactive or need to embed third-party content. With the new AMP Eleventy Plugin, it’s much simpler to use AMP components inside your templates without worrying about setting up the AMP boilerplate or importing AMP components.

AMP, at its core, is a web components framework. These components are designed with performance and accessibility in mind and can be useful in many different contexts. This plugin is a good example for how you can use AMP as just that – a component library. For example, the plugin provides the option to opt out of AMP Cache delivery and to self-host the AMP runtime. This gives you complete control on how and where your page is being served. Read on to learn more about the plugin and how to use it. 

When should you use AMP with Eleventy?

If you’re publishing a simple blog with just text and images, you don’t need to use AMP. In fact, it makes much more sense to use plain HTML + CSS in that case.

Using AMP makes sense if you’d like to use more advanced features on your site, without having to reinvent the wheel:

  • Advanced UI components such as carousels or image lightbox galleries. 
  • Visual effects such as fade-in, parallax, collapsing header and more.
  • Third-party embeds, such as YouTube, Twitter, Instagram. The good thing about AMP is that it provides a rich set of third-party integrations which are all optimized and properly sandboxed so that they don’t slow down the performance of your site.
  • Navigational features, such as an accessible, mobile friendly menu with amp-sidebar or a continuous scrolling experience across different pages with amp-next-page. These are all common features that are tiring to reinvent over and over again.

Here is an example of an image carousel which fades in on load and includes a lightbox mode. In this example, you could use AMP components directly in your markdown files. AMP components work out of the box and the AMP Eleventy plugin takes care of importing all required AMP component scripts and setting up the AMP document.

# Hello AMPHTML World

<amp-carousel lightbox amp-fx="fade-in" layout='responsive' width='600' height='400' type='slides'>
  <amp-img src='https://picsum.photos/id/1015/600/400' layout='fill'></amp-img>
  <amp-img src='https://picsum.photos/id/1016/600/400' layout='fill'></amp-img>
  <amp-img src='https://picsum.photos/id/1018/600/400' layout='fill'></amp-img>
</amp-carousel>Code language: HTML, XML (xml)
Example of the AMP Carousel with fade and lightbox

Another benefit of AMP is it’s rich set of optimized third-party integrations. Some of them are directly built-in into the AMP Eleventy plugin via shortcodes:

Checkout this video:
{% video "my-video.mp4" %}
Or this tweet (the number specifies the embed height):
{% twitter "1182321926473162752" 472 %}
Here is a Youtube video:
{% youtube "v0BVLgEEuMY" %}
And of course Instagram:
{% instagram "BMQ8i4lBTlb" %}Code language: JavaScript (javascript)

The plugin also applies web performance best practices by default. It integrates AMP Optimizer and automatically optimizes images using eleventy-img. This means you get the best possible AMP performance out-of-the-box.

There’s one thing to note though about using AMP. AMP can only ensure its performance guarantees if it is used exclusively on a page. For example, the AMP runtime can only avoid content shifts on page load if it can calculate the height of every element on the page in advance. If you require features on your page that are not supported by AMP components or amp-script, it is better to use a different technology. However, we are working on making AMP components available as standalone components to support these use cases in the future as well.

Getting started

To get started, install the AMP Eleventy plugin via NPM:

$ mkdir eleventy-amp-demo
$ cd eleventy-amp-demo
$ npm init --yes
$ npm install @ampproject/eleventy-plugin-amp --save-dev

Then add the plugin to your Eleventy config .eleventy.js:

const ampPlugin = require('@ampproject/eleventy-plugin-amp');
module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(ampPlugin);
};Code language: JavaScript (javascript)

And that’s it, now you can start creating your content:

$ echo '# Hello World

![image](https://unsplash.it/500/400)

{% twitter "1182321926473162752"  472 %}' > index.mdCode language: PHP (php)

To serve your site locally, you need to install Eleventy and run it:

$ npm install -g @11ty/eleventy
$ eleventy --serve

Tada! You can now checkout your new valid AMP site by visiting http://localhost:8080

Off cache AMP and runtime self-hosting

You can use AMP simply as a UI component library without any dependencies to an AMP Cache. There are two (optional) features  built-in in to make this this possible:

  1. Opt out of AMP caches: prevents AMP caches from serving your pages (for example when surfaced in Google Search or Bing). This can make sense, if you prefer your site not to be served from a different AMP Cache origin. This feature will remove the lightning bolt from the <html> tag which will stop AMP Caches from serving your page. 
  2. Runtime Self-Hosting: AMP is continuously being improved and to automatically get the latest features it’s best to load the AMP runtime and component scripts from cdn.ampproject.org. However, if you want more fine grained control on which AMP version to use, you can also host the AMP runtime yourself. The AMP Eleventy plugin integrates the new fetch-runtime module from AMP Toolbox, which will download the AMP runtime as part of your site build. This also offers an additional performance benefit as the initial render does not require setting up a second HTTPs connection to cdn.ampproject.org.

You can enable these features by the following options:

eleventyConfig.addPlugin(pluginAmp, {
    ampCache: false, 
    downloadAmpRuntime: true,
    ampRuntimeHost:
      process.env.ENV === 'prod' ? 'https://your-domain.com' : 'http://localhost:8080',
 });Code language: CSS (css)

Make sure to set the environment variable in your package.json build script:

"scripts": {
    "build": "ENV=prod eleventy",
    "watch": "eleventy --watch",
    "serve": "eleventy --serve"
  }Code language: JavaScript (javascript)

A glimpse into the future of even faster AMP pages

The AMP team is continuously working on improving the performance of AMP. The Eleventy plugin gives you the chance to use many of these upcoming features today:

To enable these, add the following options to your config:

eleventyConfig.addPlugin(pluginAmp, {
    ampCache: false,
    downloadAmpRuntime: true,
    ampRuntimeHost:
      process.env.ENV === 'prod' ? 'https://your-domain.com' : 'http://localhost:8080',
    experimentEsm: true,
    experimentImg: true,
    validation: false,
    imageOptimization: {
      urlPath: '/img/',
    },
  });Code language: JavaScript (javascript)

The catch here is that these are not yet supported by the AMP Validator, which means your AMP pages don’t qualify for being served from an AMP Cache. But on your origin, this will give you the best performance AMP has to offer.

Summary

Give it a try and let us know what you think! The Eleventy AMP Plugin offers a simple way to quickly create a new website with AMP. To make it even easier, we’ve also put together an AMP blog starter template you can use to get started right away.  

Posted by Sebastian Benz, Developer Advocate, Google