AMP

Announcing AMP Toolbox 1.0

Developer Experience, Websites

AMP Toolbox has been around for a while now, but I thought it’s a good idea to make a proper introduction now that we’ve reached the 1.0 milestone. In short, AMP Toolbox is a collection of command line tools and JS APIs to make it easier to successfully publish AMP pages. Each tool can be downloaded and used separately.

The 1.0 release includes two big updates:

  1. 1. A linter for AMP documents: AMP Linter reports errors and suspicious constructions such as missing or incorrectly sized images, missing CORS headers, or invalid metadata.
  2. Valid optimized AMP Support: the AMP Optimizer will now produce valid AMP, making it a lot easier to host optimized AMP pages. See the previous blog post on this for more details.

But there’s more cool stuff! Let’s take a closer look at what else is in AMP Toolbox.

AMP CLI

First of all, there’s a command line interface available for most features included in AMP Toolbox. You can install it globally via NPM:

$ npm install @ampproject/toolbox-cli
$ amp help

or you can run a one off command using NPM’s built-in `npx` tool:

$ npx @ampproject/toolbox-cli help

AMP Linter

The brand-new toolbox-linter checks your AMP documents for common mistakes and best practices:

$ amp lint https://amp.dev

PASS 1x1 images are specified by <amp-pixel>
WARN All <amp-img> have reasonable width and height
> [https://blog.amp.dev/wp-content/uploads/2019/06/cf_hero.png]: actual ratio [1999/1140 = 1.75] does not match specified [16/9 = 1.77]
> [https://blog.amp.dev/wp-content/uploads/2018/10/img_20180926_163001-01.jpeg]: actual ratio [3680/2314 = 1.59] does not match specified [16/9 = 1.77]
PASS Videos are under 4MB
PASS <amp-video><source/></amp-video> syntax is used for video
PASS Endpoints are accessible from cache
PASS Endpoints are accessible from origin
FAIL <meta charset> is the first <meta> tag
> <meta charset> not the first <meta> tag
PASS Runtime is preloaded

Or without installation:

$ npx @ampproject/toolbox-cli lint https://amp.dev

AMP Linter’s SXG mode is invaluable when adding SXG support to your site:

$ amp lint -f sxg https://amp.dev

PASS /amppkg/ is forwarded correctly
PASS application/signed-exchange content negotiation is correct
PASS dump-signedexchange -verify does not report errors
PASS vary header is correct

AMP Optimizer

AMP Optimizer is a tool to server-side enhance the rendering performance of AMP pages. AMP Optimizer implements AMP performance best practices and supports AMP server-side-rendering. These optimizations can result in up to 50% faster FCP times. 

You can play around with it via the CLI:

$ amp optimize https://amp.dev
$ amp optimize file.html

However, for production, it’s better to integrate toolbox-optimizer as part of your build or rendering chain. There’s also an Express middleware available: amp-optimizer-express that will apply AMP server-side-rendering on the fly.

AMP Cache URLs

For testing, it’s a good idea to check whether an AMP page works on all AMP caches. Use toolbox-cache-url for translating origin URLs to the AMP Cache URL format.

$ amp curls https://amp.dev

https://amp-dev.cdn.ampproject.org/c/s/amp.dev
https://amp-dev.amp.cloudflare.com/c/s/amp.dev
https://amp-dev.bing-amp.com/c/s/amp.dev

Or for a specific cache:

$ amp curls --cache=google https://amp.dev

https://amp-dev.cdn.ampproject.org/c/s/amp.dev

AMP Cache List

There’s also an API available to get a list of all official AMP Caches. This can be useful when implementing CORS in your backend:

const Caches = require('@ampproject/toolbox-cache-list');

Caches.list().then(console.log);

Sometimes it’s necessary to quickly update or remove AMP documents from an AMP Cache. Using the CLI version of the AMP Update Cache API this becomes very easy: 

$ amp update-cache https://www.example.com/ --privateKey /path/to/private-key.pem

Of course, there’s also an API version available as part of the toolbox-update-cache package.

AMP CORS

Speaking of CORS, many AMP components, such as amp-list or amp-state, take advantage of remote endpoints by using CORS requests. Part of AMP toolbox is a connect/express middleware which will automatically add all CORS headers required by your AMP pages. Simply add the toolbox-cors middleware to your express application and you can forget about CORS when serving your AMP pages:

const express = require('express');
const ampCors = require('@ampproject/toolbox-cors');

const app = express();

// That's it!
app.use(ampCors())

AMP Validation Rules

In case you want to implement AMP specific code completion for your favorite text editor, take a look at amp-validator-rules: a javascript library for querying AMP validator rules. Here is a sample that will list all valid attributes for the amp-img element:

import validatorRules from '@ampproject/toolbox-validator-rules';
 
validatorRules.fetch().then(rules => {
  // Get all website specific tag rules ...
  const tags = rules.getTagsForFormat('AMP');
  // ...find the definition of the amp-img tag...
  const ampImg = tags.find(e => e.tagName === 'AMP-IMG');
 
  const ampImgAttrs = ampImg.attrs
    // ...filter global, layout and amp-bind attributes...
    .filter(e => !e.name.startsWith('[') && !e.global && !e.layout)
    // ...extract the name...
    .map(e => e.name)
    // ...sort alphabetically...
    .sort();
 
  // ...and display result in the console.
  console.log(ampImgAttrs);
});

Summary

AMP Toolbox aims to simplify common tasks either via command line or APIs. If you think there’s a piece of functionality missing please let us know!

Posted by Sebastian Benz, Developer Advocate, Google