Lessons Learned Working with Google's AMP

So you want to add Accelerated Mobile Pages, or AMP, to your site and aren't sure where to start? Well aside from AMP's robust documentation this is a good place to look for some lessons learned while integrating it to Viget's main site.

Lesson 1 - AMP is different

Maybe you have used Facebook Instant Articles and liked how easy it was to make a custom feed to export, or you have used Apple News and had a nice time using their News Publisher app. However, AMP's barrier to entry is much higher. AMP uses an opinionated tagging system, which requires more than a few slight configurations to your existing site to work.

To start, AMP's focus is speed. It wants you to load the barest of bones page. This means your CSS must be inlined in the head (no external links, sorry) and must be 50Kb or less in size, no JavaScript (unless it's AMP's JavaScript), and you must use AMP's specific AMP elements instead of native HTML. If you were paying attention to that last sentence, you probably realized that at least a majority of those requirements would force you to rethink how you are currently running your site.

Let's get into each of these requirements, and what this means for you if you want to use AMP yourself.

Reorganizing and Optimizing Your CSS for AMP

At Viget, we only use AMP on our Articles pages, that means this very blog post you are reading is optimized for AMP, and as of writing, no other section of the site is. AMP forces some good theories on developers - it forces developers to only load relevant assets to what the user is currently viewing. This means if a user is only viewing a blog post, they should not be required to load the CSS and JS for the About section too. I make a similar argument in my HTTP/2 primer article as well.

Obviously the purpose of capping CSS and forcing it inline is speed. If the CSS is inlined in the head, the browser does not have to send a request and it loads very quickly. However, implementing this can be a challenge. It forces you, as a developer, to find the least common denominator of styles you can load into your AMP page.

As I said, we do our Articles in AMP, so this required me to find all of the necessary styles for our Articles section and compile them out to their own separate amp.css file. Fortunately, Viget does not use AMP in any other section of our site yet, but if we did decide to go this route, we would most likely have to partition off certain sections to specific AMP CSS files.

For example, the current amp.css would most likely become amp-article.css so that I could load the amp-work.css file in the Work section. This way there is no unnecessary overlap of styles. Each page only gets the styles of elements that could appear on it.

One final thought on CSS optimization is that you probably will not to focus too much on responsive development and media queries. Since the M in AMP stands for mobile, it will only load on mobile devices. Therefore prioritizing your styles to mobile and tablet views is all that's needed, while removing anything larger.

We also use Craft at Viget, and Craft has a really great inliner plugin called Inlin-Craft. There are many other methods for inlining code into your project, this is just the one we typically use. So in AMP's case, you would place a tag in the head like so:

Turning Off Your JavaScript

This one seems pretty apparent, but some may disagree with the reasoning. It boils down to simply removing your JavaScript and any component that requires JavaScript to load. However, (and this is a big however), JavaScript must be enabled for AMP to work. This may seem like a contradiction but AMP uses lazy loading techniques to load your content quickly. So really, AMP doesn't have a problem with JavaScript, just your JavaScript.

Learning AMP's HTML

If the previous stuff wasn't difficult for you, this next part probably will be. AMP will not load many standard HTML elements in favor of their own markup. So instead of loading an `<img>` you must mark up your images as `<amp-img>`. This allows AMP to categorize your content and load it at a more efficient rate than normal. If you didn't know AMP requires this and you want to cringe, you can check out the full list of custom AMP HTML elements on their docs. Yea, that's a pretty big list, right?

So what does this mean? Well if you weren't paying attention to my previous point, you may think that you can just run some JavaScript to change out all your HTML to custom AMP elements when required, but… well you can't use your own JS, remember? So AMP sort of forces you to create alternate versions of all your components that use any sort of "special" elements (and by "special" I mean most standard HTML elements). As a pretty good rule of thumb, if it's not text, AMP probably has a unique element for it.

It's kind of a bummer, but you will have to maintain two separate versions of any section of content that goes up to AMP - one that goes to your normal production site and one that is optimized for AMP. It will probably be pretty hard to manage, but there is light at the end of the tunnel.

Lesson 2 - AMP makes it easy to test

Ok, so Lesson 1 may have been a pretty tough one to get through without turning back to whoever asked you to integrate AMP and firmly saying "NO", but they actually do a great job at making it quick and easy to test once it is up and running.

AMP has a few really great tools that can help you troubleshoot and make quick fixes. The best one is the AMP Validator plugin for Chrome. This gives you a really simple interface for testing. Once it is installed it will show you if the page you are currently on has an AMP view to check out, by turning blue.

If you click on it, it will take you to the AMP view as well as a green lightning bolt if it is looking good and all tests pass.

Or it will turn red with the number of errors you currently have.

Clicking on the red bolt will open up a panel, instructing you which lines of your code have specific errors and how to fix. This is a really wonderful tool that if didn't exist, I would probably still be working on my first AMP integration to this day.

If you have the AMP Validator plugin, you can check this page out for yourself in the AMP format and see the green bolt for yourself (if it's red, send me a comment below!)

The AMP Validator plugin leverages AMP's Validator Browser IDE which allows you to just copy and paste in code and play around with it until it validates. To me this is a less useful tool, because all of the projects I work on use templating or compilation to output files, so I am very rarely, if ever, using straight HTML and CSS. However it is definitely useful for immediate feedback and isolate issues in your code.

Lesson 3 - It's going to be frustrating

You probably picked up that integrating AMP on your site can be difficult and frustrating. As I mentioned before, it almost guarantees that you will need to maintain two separate yet similar sites - your normal production site, and one for AMP. In an ideal scenario, you would know at the beginning of a project or site build that you want to have AMP, rather than retrofitting it in later. Many decisions for your project will be made differently if you know you will be using AMP, so allowing that to be a part of the opening discussions is highly recommended.

If you are retrofitting an existing site to AMP, it is probably best to add lots of buffer time to any estimation you may make about the timeframe this will take. Many times when retrofitting a site for AMP, I felt like I was fighting Hydra, in that I would resolve one bug and 20 more would pop up in its place. Having some extra time to either work through all the example tutorials, check out some third party tutorials like AMP by Example or even to tear down your work to start over once you realize a huge mistake will absolutely be useful.

Maybe integrating AMP is a decision you get to make, maybe it was a decision made by someone else and requested that you execute. Either way AMP is a promising and easy way for your audience to reach your content. It will be a challenge to integrate, but the effort will be worth it in the long run.

Also, if you are interested in seeing the bigger picture of mobile publishing formats like Apple News and Facebook Instant Articles in relation to AMP, check out Ben Travis' detailed post that compares all three.