Integrating AMP into an Existing Web Site

April 02, 2020  •  5 min read
  • AMP
  • Mobile Design

Last year we added, a health and wellness website, to our Healthline family of sites. Spearheaded from that addition, we built AMP into our multi-tenant platform. This gave all our web sites AMP functionality.


What is AMP?


AMP (Accelerated Mobile Pages) is a web component framework created by Google. Following its rules and using its components produces fast-loading, mobile-first web sites. Before the platform migration, was serving AMP content. Deciding to proceed forward with adding AMP back would depend on what benefits we would gain. As software engineers, we love “shiny” new technology.

Speed. Give me what I need.

We are always seeking ways to enhance our performance. Performance affects not only our user experience but also our search rankings. Back in 2015 Google announced the addition of mobile-friendliness as a ranking signal. Mobile-friendliness includes performance. AMP’s website claims that their documents load “so fast they appear to load instantly.” The AMP restrictions and optimizations combined decrease both load time and data usage. In theory, AMP could improve our user experience, search rankings, and site traffic.

There are 7 optimizations that when combined result in these “instant” page loads. One such optimization is that Google serves and caches AMP documents. Google boasts a considerable distributed content network making load time even quicker.

Given the benefits, we moved forward with adding AMP.


We run a headless Wordpress implementation; its data requested through API calls. Our web sites run on Node.js and generated by server-side rendered React. In such an environment, we had a few choices for how to put in place AMP support.

  1. Reuse as much code as possible to keep code duplication and size increases minimal. This might add complexity to the existing code. When extending functionality, you risk breaking the single responsibility and open/closed principle.

  2. Use a theme-esc approach. We’d create a new Next.js template with new React-rendered AMP components. These files would all exist in one folder. This creates code duplication and increases the code-base but promotes encapsulation.

  3. Use Wordpress to serve the AMP documents instead of Node.js. There are a bunch of plugins to create AMP content. We would need to create a basic Wordpress theme for each of our websites. This too would increase our code-base and add yet another code-set/system to maintain.

After reviewing our code, we determined a mix of both 1 and 2 would be best. We’d do the following:

  • Add the endpoint /amp to our routes in Hapi.js.
  • Duplicate our base Next.js template and strip it down.
  • Reuse those React components that need slight modifications.
  • Create components for major modifications.

The Nitty Gritty

Like HTML documents, AMP documents have validation rules.


All CSS is to be inline and enclosed within an <amp-custom> tag. Also, the amount of CSS cannot exceed 50Kb in size. This means no external CSS files. Fortunately, we use the CSS-in-JS library Emotion.js that outputs the CSS inline. We wrapped the content in <amp-custom> and that was it.

Using !important in a style definition is invalid. We had a few places where this was an issue. After resolving those issues, we had valid CSS for AMP.

Client JavaScript

External/third-party client JavaScript is invalid except for the AMP component framework. Most of our site uses server-side React and so our client-side JavaScript usage is minimal. This made it easier to remove JS includes and replace them on a case-by-case basis with AMP components. Most JavaScript libraries have an AMP counterpart. Each component has a unique set of validation rules listed in its documentation.

Final Touches

Once all the pages were valid, we added an <link> tag inside the <head> blocks of both our standard and AMP Next.js templates. Each <link> points to its counterpart. This addition enables Google’s indexing robot to discover both pages.


Validation is paramount for AMP documents. Google only caches and serves valid AMP documents. This makes the AMP validation website a necessary tool. The validation website also provides a Google Chrome plugin. We’re considering a command-line validation tool in our build to catch regressions. With our plethora of articles, it was imprudent and impossible to check validity one page at a time. Thank goodness Google provides a means to check an entire site. Their Search Console can generate a report listing validation errors across a domain.


While the validation tools are nice, they seem primitive. The error messages can be hard to understand. This leads to a lot of guesswork and constant checking and re-checking.

Some validation rules were a bit of a challenge to follow. Inline images in AMP need both height and width set to be valid. Our layout uses <div> containers with min and max CSS properties to control image width and height. We had to modify the Wordpress API to include those dimensions.

We came up with some creative solutions to fix validation errors. We have a show/hide toggle for showing an article’s sources. We chose the <amp-accordion> component as its replacement. According to its documentation,

  • Each <section> must contain exactly two direct children.
  • The first child (of the section) represents the heading for the section and must be a heading element (one of h1, h2, …, h6, header).

We wrapped the toggle area with <header> to follow the validation rules.

Having AMP-invalid HTML tags in our article body created another challenge. With our headless setup, we request the article body from Wordpress. Using the Search Console report we found articles with AMP-invalid tags such as <font>. Being few in number we removed those tags from individual articles inside WordPress.


Adding AMP to our existing website wasn’t too difficult. Yes, we hit some snags with validation and the validation tools were not always helpful. We hope the effort pays off. Only time will tell.


Cover photo by chuttersnap on Unsplash

Copyright © Rebecca Vest and Camp Code Blog, 2022. Unauthorized use and/or duplication of this material without express and written permission from this site's author and/or owner is strictly prohibited. Excerpts and links may be used, provided that full and clear credit is given to Rebecca Vest and the Camp Code Blog with appropriate and specific direction to the original content. Built with Gatsby.