@ampproject/toolbox-optimizer
Advanced tools
AMP Optimizer is a tool to simplify creating AMP pages and improve AMP rendering performance. AMP Optimizer implements AMP performance best practices and supports AMP server-side-rendering. By default, it will perform the following optimizations:
amp-script code.The performance optimizations can improve page rendering times by up to 50%. You can read more about the potential performance gains in this blog post. To give it a try, check out the online playground.
Good to know:
Install via:
npm install @ampproject/toolbox-optimizer
Minimal usage:
const AmpOptimizer = require('@ampproject/toolbox-optimizer');
const ampOptimizer = AmpOptimizer.create();
const originalHtml = `
<!doctype html>
<html ⚡>
...
</html>`;
ampOptimizer.transformHtml(originalHtml).then((optimizedHtml) => {
console.log(optimizedHtml);
});
You can find a sample implementation here. If you're using express to serve your site, you can use the AMP Optimizer Middleware.
It's possible to pass incomplete documents and AMP Optimizer will add any missing tags and extension imports required by a valid AMP document.
const originalHtml = `
<h1>Hello World!</h1>
<amp-twitter width="375"
height="472"
layout="responsive"
data-tweetid="1182321926473162752">
</amp-twitter>
`;
// you can pass the canonical URL, default is `.`
const opts = {
canonical: '/example.html'
}
ampOptimizer.transformHtml(originalHtml, params).then((optimizedHtml) => {
// optimizedHtml will be a valid AMP document
console.log(optimizedHtml);
});
AMP Optimizer supports converting Markdown to AMPHTML. A typical conversion flow would be:
README.md => HTML => AMP Optimizer => valid AMP
The AMP Optimizer converts <img> tags into <amp-img> or <amp-anim> tags when in Markdown mode. Enable Markdown mode via markdown : true. AMP Optimizer will try to resolve image dimensions from the actual files. Images wider than 320px will automatically get an intrinsic layout.
All other Markdown features are already supported by AMP.
You can pass an additional option imageBasePath to specify a base path used to resolve an image during build, this can be a file system path or URL prefix.
Important: for image size detection to work, an optional dependency
probe-image-size needs to be installed via NPM.
npm install probe-image-size --save-dev
Example:
const AmpOptimizer = require('@ampproject/toolbox-optimizer');
const md = require('markdown-it')({
// don't sanitize html if you want to support AMP components in Markdown
html: true,
});
// enable markdown mode
const ampOptimizer = AmpOptimizer.create({
markdown: true,
});
const markdown = `
# Markdown 🤯
Here is an image declared in Markdown syntax:
.
You can directly declare AMP components:
<amp-twitter width="375"
height="472"
layout="responsive"
data-tweetid="1182321926473162752">
</amp-twitter>
Any missing extensions will be automatically imported.
`;
const html = md.render(markdown);
const amphtml = await ampOptimizer.transformHtml(html, {
canonical: filePath,
});
You can find a working sample here.
AMP Optimizer supports custom HTML transformations:
const AmpOptimizer = require('@ampproject/toolbox-optimizer');
const {createElement, firstChildByTag, appendChild} = AmpOptimizer.NodeUtils;
class CustomTransformer {
constructor(config) {
this.log_ = config.log.tag('CUSTOM');
}
transform(tree, params) {
this.log_.info('Running custom transformation for ', params.filePath);
const html = firstChildByTag(tree, 'html');
if (!html) return;
const head = firstChildByTag(html, 'head');
if (!head) return;
const desc = createElement('meta', {
name: 'description',
content: 'this is just a demo',
});
appendChild(head, desc);
}
}
// it's best to run custom transformers first
const customTransformations = [CustomTransformer, ...AmpOptimizer.TRANSFORMATIONS_AMP_FIRST];
// pass custom transformers when creating the optimizer
const optimizer = AmpOptimizer.create({
transformations: customTransformations,
});
// you can add custom parameters on a per document basis
const transformedHtml = await optimizer.transformHtml(html, {
filePath,
});
Checkout the samples to learn how to customize AMP Optimizer.
There's also a command line version available:
$ npx @ampproject/toolbox-cli myFile.html
The biggest performance gain results from removing the AMP boilerplate code. However, under some circumstances it's not possible to remove the boilerplate code:
amp-experiment, amp-story or amp-dynamic-css-classes components are used (code).media, sizes or heights attribute (documentation). A simple workaround is to replace the media, sizes or heights attributes with normal CSS media queries.To find out, why the AMP boilerplate could not be removed, enable verbose mode:
// globally
const optimizer = ampOptimizer.create({
verbose: true
} );
... or for individual pages:
// per transformation
ampOptimizer.transformHtml(originalHtml, {
verbose: true
})
Applying the transformations to an AMP file consumes additional server resources. Also, since the entire file is needed to apply the transformations, it also becomes impossible to stream the response while applying it. In order to avoid server overhead, if the set of AMP files to be transformed is known in advance, transformations should be run at build time.
Most websites have a more dynamic nature though and are not able to apply the transformations statically. For such cases it is possible to run the transformations after AMP pages are rendered, e.g. in an Express middleware. In that case, to achieve best performance, it's best to cache transformed pages for subsequent requests. Caching can take place on the CDN level, on the site's internal infrastructure (eg: Memcached), or even on the server itself, if the set of pages is small enough to fit in memory.
AMP Optimizer inlines CSS styles required by AMP. To make sure, that the inlined CSS stays in sync with the latest AMP release, we recommend to re-generate pages at least once a weekOut-of-sync CSS will not break your page, but it could theoretically cause AMP components to briefly appear with the "wrong" styles, such as being visible when they should be hidden. The good news is that these glitches will only be temporary, because as soon as the AMP JS starts, it will check the inlined CSS and update it if required.
Warning: these features are experimental and might result in invalid AMP pages.
When using experimental features resulting in invalid AMP it's best to setup paired AMP mode. Paired AMP mode will add <link rel=amphtml href=${ampUrl}> to the transformed page, were ampUrl needs to point to the valid version of this page.
Example:
const optimizer = AmpOptimizer.create({
transformations: AmpOptimizer.TRANSFORMATIONS_PAIRED_AMP,
});
const ampFilePath = filePath.substring(1, filePath.length)
.replace('.html', '.amp.html');
const transformedHtml = await optimizer.transformHtml(html, {
// needed to calculate the `<link rel=amphtml href=${ampUrl}>`
ampUrl: ampFilePath,
});
The ampRuntimeVersion parameter will rewrite all AMP runtime and extension imports to the specified version. For example:
https://cdn.ampproject.org/v0.js
will be replaced with:
https://cdn.ampproject.org/rtv/001515617716922/v0.js
Versioning the AMP runtime URLs has one main benefit: versioned AMP runtime URLs are served with a longer max-age than the unversioned ones. This means AMP pages served with versioned AMP runtime benefit from better browser caching.
Important: when using versioned AMP runtime URLs make sure to invalidate all caches whenever a new AMP runtime is released. This is to ensure that your AMP pages always use the latest version of the AMP runtime.
You can use @ampproject/toolbox-runtime-version to retrieve the latest version of the AMP runtime. Here is a sample to apply the optimizations including versioning the URLs:
const ampOptimizer = require('@ampproject/toolbox-optimizer');
const ampRuntimeVersion = await runtimeVersion.currentVersion();
// The input string
const originalHtml = `
<!doctype html>
<html ⚡>
...
`
// Additional options can be passed as the second argument
const optimizedHtml = await ampOptimizer.transformHtml(originalHtml, {
ampUrl: 'canonical.amp.html',
ampRuntimeVersion: ampRuntimeVersion
});
console.log(optimizedHtml);
Add placeholders for amp-img and amp-video posters. The placeholders are blurry versions of the corresponding original source. The blur will be displayed as the <amp-img> is rendering, and will fade out once the element is loaded. The current requirements of appending a blurry placeholder is for the element is to be a JPEG that is either responsive or a poster for an amp-video.
Important: blurry image placeholder computation is computationally expensive. Make sure to only use it for static or cached pages.
This transformer supports the following options:
blurredPlaceholders: Enables blurry image placeholder generation. Default is false.imageBasePath: specifies a base path used to resolve an image during build.maxBlurredPlaceholders: Specifies the max number of blurred images. Defaults to 5.blurredPlaceholdersCacheSize: Specifies the max number of blurred images to be cached
to avoid expensive recalculation. Set to 0 if caching should be disabled. Set to -1 if
all placeholders should be cached (good for static sites). Defaults to 30.Usage:
const optimizer = AmpOptimizer.create({
// blurry image placeholders are currently not considered valid AMP
// hence it's recommended to setup paired AMP mode when enabling this feature.
transformations: AmpOptimizer.TRANSFORMATIONS_PAIRED_AMP,
blurredPlaceholders: true,
});
It's possible to rewrite the AMP framework and component imports to a different domain than cdn.ampproject.org.
Example:
const ampOptimizer = require('@ampproject/toolbox-optimizer');
// The input string
const originalHtml = `
<!doctype html>
<html ⚡>
...
`
// Additional options can be passed as the second argument
const optimizedHtml = await ampOptimizer.transformHtml(originalHtml, {
ampUrl: 'canonical.amp.html',
// this will rewrite https://cdn.ampproject.org/v0.js to /amp/v0.js
ampUrlPrefix: '/amp'
});
console.log(optimizedHtml);
AMP Optimizer uses a snapshot based testing approach. To execute the tests, run in the project root:
$ npm run test:node
Transformer tests are located in:
- spec/transformers/valid/TransformerName/test-name/
expected_output.html
input.html
The transformation input is defined in input.html, whereas expected_output.html contains the expected
outcome of the transformation. Don't edit expected_output.html manually, instead, after changing
a transformer implementation, run:
$ npm run test:optimizer:snapshot
to store a new snapshot version in expected_output.html.
2.0.1
optimizer
linter
cli, lighthouse-plugin-amp, linter, optimizer
FAQs
Server-side rendering for AMPs.
The npm package @ampproject/toolbox-optimizer receives a total of 28,168 weekly downloads. As such, @ampproject/toolbox-optimizer popularity was classified as popular.
We found that @ampproject/toolbox-optimizer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 16 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.