In this blog post we’re going to look at how you can optimize the page experience of your AMP pages by running AMP Optimizer in a Cloudflare Worker.

A great user experience on the web means more than just having a website that loads fast (although that continues to be a critical part of the user experience). There are many factors that contributing to a great experience, such as:

• Loading speed

• Responsiveness

• Content stability

Traditionally, these have been hard to measure, but with Core Web Vitals we now have a new way to measure user experience on the web. The key is: Core Web Vitals are based on real world user data. To score well on Core Web Vitals you need to make sure that your website performs well - for all your users around the world.

Image URL

This becomes even more important soon, as Core Web Vitals are also going to be a signal in the upcoming page experience ranking update in Google Search. You can find more details in the page experience FAQ.

AMP is an open source web components framework that has been developed with page experience in mind. AMP ensures a good page experience by providing guardrails that help avoid common performance pitfalls. For example, AMP features a static layout system, which avoids content shifts by design.

However, AMP pages can still fail Core Web Vitals. The reason for this is clear: some performance best practices required for performing well on Core Web Vitals can’t be implemented at client-side. For example, image optimization, fast server-response times and effective font-loading are all critical for a good user experience, but need to be done on the server. Even AMP documents themselves can be further optimized. For example, AMP’s layout system can be pre-rendered at build or serving time which greatly improves page load times while still ensuring that there are no content jumps.

The good news is, if an AMP page is surfaced in Google Search or Bing, it’ll be served from an AMP Cache which performs all these optimizations for you. But when someone visits your AMP page directly, for example through a link shared on social media, they won’t get the same experience. In order to ensure that you are getting great Core Web Vitals scores for all your users, it is very important to optimize your AMP pages on your origin as well!

To help with this, the AMP team has created AMP Optimizers, which will automatically perform common performance best practices for you. Using AMP Optimizers combined with Cloudflare Workers makes it super easy to serve optimized AMP pages on your own origin.

We are happy to announce a new AMP Optimizer integration for Cloudflare Workers. So far, there are two AMP Optimizer versions available: one for NodeJS and one for PHP. Both take an AMP HTML document as input and turn it into an optimized AMP HTML document. Depending on when your pages are created, one of these needs to be run either as part of your build system or in on your backend as part of your rendering pipeline. However, integrating an AMP Optimizer is not always straightforward, for example if you’re not using PHP or NodeJS in your backend or when you don’t control the hosting environment.

With the Cloudflare Worker integration for AMP Optimizer you can seamlessly optimize all your AMP pages. You can find installation instructions on the Github repository.

Let’s dive into how the Cloudflare Worker works, so that we can get a better understanding of where it optimises things.

Whenever a request comes in for an HTML file (1), the Worker will first check in the global cache if an optimised version has already been generated (2). If that is not the case (3), the Worker will request the version of the file from your origin (4)(5), optimize the document if it is using AMP (6), and return that to the user (7). Only after the response has been fully streamed to the user will we start saving the generated version in the cache (8).

For subsequent requests, in a Worker anywhere else in the world, the result will be retrieved from the global KV cache, cached locally in that data center and returned straight away.

Because the AMP Optimizer parses the HTML document, it will discover what other resources are used, and will add preload tags for external resources such as fonts and hero images.

Images are often the biggest contributors to the total download size of a web page. Customers on the Business or Enterprise plans can automatically make use of the Cloudflare Image Optimization functionality. For those customers, the AMP Optimizer can automatically generate image source sets with links for the Cloudflare Image Optimizer.

Image sourcesets give the browser different options to pick the most appropriate image size for that particular browser viewport. This can greatly reduce the size of the image downloads for, say, a low end mobile phone, which needs much smaller images than a 4K desktop monitor.

While most of the requests will be handled very quickly, even the ones that need optimising, the optimisation of large files can take more than 50ms of CPU time. Which is why Workers Unbound is a perfect match for the AMP Optimizer Worker.

Workers Unbound allows Workers to execute for up to 30 seconds, so that even if it does take a bit longer than 50ms to optimize a document, your users will never see any errors.

Web performance is much more complex than any synthetic test can prove, so you should absolutely do your own performance testing on your own sites. But here is an example of a regular AMP page with and without the Cloudflare Worker AMP Optimizer in front of it. This is tested on a simulated Moto G4 on a fast 3G network.

Here is the full WegPageTest data if you want to explore this example further.

There is also an example benchmark script you can adapt if you want to run performance tests on your own site.

Cloudflare Workers offer a simple way to prepare your AMP pages for Google’s upcoming page experience launch. They offer a seamless integration that doesn’t require any changes in your CMS or server. Even better — with the new Cloudflare Workers Unbound, it becomes possible to perform even more advanced optimizations. Check out the cloudflare-amp-optimizer repository for more details on how to get started.

The promise of the AMP (Accelerated Mobile Pages) project was that it would make the web, and, in particular, the mobile web, much more pleasant to surf. The AMP HTML framework was designed to make web pages load quickly, and not distract the user with extraneous content that took them away from focusing on the web page’s content.

It was particularly aimed at publishers (such as news organizations) that wanted to provide the best, fastest web experience for readers catching up on news stories and in depth articles while on the move. It later became valuable for any site which values their mobile performance including e-commerce stores, job boards, and media sites.

As well as the AMP HTML framework, AMP also made use of caches that store copies of AMP content close to end users so that they load as quickly as possible. Although this cache make loading web pages much, much faster they introduce a problem: An AMP page served from Google’s cache has a URL starting with https://google.com/amp/. This can be incredibly confusing for end users.

Users have become used to looking at the navigation bar in a web browser to see what web site they are visiting. The AMP cache breaks that experience. For example, here’s a news story from the BBC website viewed through Google’s AMP cache:

Notice how the browser says the page is from google.com. That’s because of the AMP cache. This made the page load very quickly, but can be confusing. To help “fix” that problem Google shows that actual site at the top of the AMP page. There you can see that it was bbc.co.uk. Clicking on bbc.co.uk brings you to the same page served by the BBC’s web servers with bbc.co.uk in the web browser’s navigation bar:

But the problems with the AMP cache approach are deeper than just some confusion on the part of the user. By serving the page from Google’s cache there’s no way for the reader to check the authenticity of the page; when it’s served directly from, say, the BBC the user has the assurance of the domain name, a green lock indicating that the SSL certificate is valid and can even click on the lock to get details of the certificate.

Last November we announced a technical solution to these problems that would allow AMP pages to be served from a cache while retaining the original page URL and all its benefits. The in depth technical blog post by Gabbi Fisher and Avery Harnish gives the full details. The solution makes use of Web Packaging (which incorporates some clever use of cryptography) to allow the cache (run by Google, Cloudflare or others) to keep a copy of an AMP page and serve it quickly to the end user, but to also contain cryptographic proof of where the page originally came from.

In cooperation with a browser that understands Web Packaging this means that a page can be stored in an AMP cache and served quickly from it while showing the original site URL in the browser’s navigation bar. A major win all round!

We’re calling this “AMP Real URL” and it’s free to all of our customers starting today.

Google’s AMP Crawler downloads the content of your website and stores it in the AMP Cache many times a day. If your site has AMP Real URL enabled Cloudflare will digitally sign the content we provide to that crawler, cryptographically proving it was generated by you. That signature is all a modern browser (currently just Chrome on Android) needs to show the correct URL in the address bar when a visitor arrives to your AMP content from Google’s search results.

Gone is the hated grey bar, all your visitors see is your proper URL:

Importantly your site is still being served from Google’s AMP cache just as before; all of this comes without any cost to your SEO or web performance.

Since our original announcement we’ve had a chance to engage with dozens of members of the publishing and e-commerce community and would like to share what we’ve learned.

The Google-initiated AMP Project drives a huge percentage of mobile traffic and has greatly improved the experience of browsing the Internet on a phone. Many of the sites we have spoken to get as much as 50% of their web traffic through AMP, and the speed benefit it provides directly translates to better conversion rates.

AMP Real URL provides some serious benefits to sites which use AMP:

• Brand Protection: Web users have been trained that the URL in the address bar has significance. Having google.com at the top of a page of content hurts the publisher’s ability to maintain a unique presence on the Internet.

• Easier Analytics: AMP Real URL greatly simplifies web analytics for its users by allowing all visitors, AMP or otherwise, to coexist on the same tracking domain.

• Increased Screen Space: Historically when AMP was used room would be taken for a “grey bar” at the top of your site to show the real URL. With AMP Real URL that’s simply not necessary.

• Reduced Bounce Rate: We believe website visitors are less likely to bounce back to Google or another site when the publisher’s actual domain is in the address bar, but we will gather more data about this as AMP Real URL is rolled out.

• Content Signing: By relying on cryptographic techniques, AMP Real URL ensures that the content delivered to visitors has not been manipulated protecting the sites and brands it is used on. It’s now not possible for any external party to add, remove, or modify the content of a site.

We also spoke to Internet users of AMP, and there certainly are frustrations. There are some users who struggle with its complexity, or sites simply fail to load for them. Others are annoyed and confused with the “grey bar” at the top of the page and the gymnastics it requires to get a page’s original URL. Finally, there are folks who would like to ensure that Google is not modifying the content of pages as they travel through the AMP cache.

AMP Real URL happily fixes all of these issues. It ensures that sites are cryptographically signed which protects them from being modified by Google or anyone else, even when physically delivered from a domain you do not control. If the site is changed in any way the browser ensures the site’s real URL will no longer appear. It also greatly simplifies AMP, fixing many of the reliability issues people experience: AMP Real URL-powered links aren’t opened using the complex iframe mechanics used by AMP traditionally, instead they are loaded as any other website (Google uses rel=”prefetch” to get much of the same performance benefit). Finally, the “grey bar” is unnecessary, as the correct URL is right in the address bar at the top of the page, and copying the URL of a site to save or share works just as it does for non-AMP websites.

We are also taking this opportunity to sunset the other AMP products and experiments we have built over the years like Ampersand and Firebolt. Those products were innovative but we have learned that publishers value AMP products which pair well with Google’s search results, not which live outside it. Users of those older products were informed several weeks ago that they will be gradually shut down to focus our attention on AMP Real URL.

Google is rolling out support for AMP Real URL (referred to as Signed Exchanges outside Cloudflare) today, beginning with the primary Google search results. Over time, the hope is they will expand it to other areas of the search results page including the “Top Stories” news area at the top of the page. This makes AMP Real URL most valuable today for sites which get most of their AMP traffic from the primary search results like e-commerce, job boards, and ad-supported sites. News publishers can and should enable AMP Real URL, but the benefit they experience now will be from search results which live outside the “Top Stories” box. AMP Real URL is only supported in the Chrome browser at this time, but we are optimistic it will be supported more widely as its benefit to Internet users becomes clear.

After speaking with publishers and with Internet users, we have decided not to charge for AMP Real URL. This is not because our customers haven’t been excited or willing to pay for it, AMP makes up a huge component of many site’s traffic. Our motivation is the same as for offering CDN or SSL services to millions of customers free of charge, we are here to help build a better Internet and improving AMP is a huge step in that direction. We believe AMP Real URL is a technology which will fundamentally change the mobile web for the better and should be adopted by every AMP-supporting site. We do have another motive: we are hoping that this will motivate potential customers who value AMP to choose Cloudflare.

Beginning today you will find a new section on the Speed tab of your Cloudflare dashboard:

We will be rolling out support for AMP Real URL in stages over the next few weeks. Enable it now and we will notify you when it is activated on your domain. If you are an interested enterprise customer please reach out so we can expedite your activation.

We'll leave you with some perspectives from the early users of AMP Real URL:

"The performance benefits of AMP deliver value to our business and we are excited to see how AMP Real URL is able to take that even further"

— Solomon Moskalenko, Director of Interactive, US Xpress Trucking, The Johnson Group

"AMP is a crucial part of helping our business to grow and reach consumers everywhere. With AMP Real URL, we now have more control over our brand and can run analytics on our business site."

— Sumantro Da, Sr Director, Product Innovations & Growth Brands GM, 1-800-FLOWERS.COM

“AMP has played a key role in helping us to more effectively reach our audience and develop our online community, we’re keen to use AMP Real URL to better manage our online presence and keep our users engaged on the site.”

— Andrew Warner, CTO of Genius

Today, we’re excited to announce our solution for arguably the biggest issue affecting Accelerated Mobile Pages (AMP): the inability to use real origin URLs when serving AMP-cached content. To allow AMP caches to serve content under its origin URL, we implemented HTTP signed exchanges, which extend authenticity and integrity to content cached and served on behalf of a publisher. This logic lives on Cloudflare Workers, meaning that adding HTTP signed exchanges to your content is just a simple Workers application away. Publishers on Cloudflare can now take advantage of AMP performance and have AMP caches serve content with their origin URLs. We're thrilled to use Workers as a core component of this solution.

HTTP signed exchanges are a crucial component of the emerging Web Packaging standard, a set of protocols used to package websites for distribution through optimized delivery systems like Google AMP. This announcement comes just in time for Chrome Dev Summit 2018, where our colleague Rustam Lalkaka spoke about our efforts to advance the Web Packaging standard.

You may already see the need for Web Packaging on a daily basis. On your smartphone, perhaps you’ve searched for Christmas greens, visited 1-800-Flowers directly from Google, and have been surprised to see content served under the URL https://google.com/amp/1800flowers.com/blog/flower-facts/types-of-christmas-greens/amp. This is an instance of AMP in action, where Google serves cached content so your desired web page loads faster.

Visiting 1-800 Flowers through AMP without HTTP signed exchange

Google cannot serve cached content under publisher URLs for clear security reasons. To securely present content from a URL, a TLS certificate for its domain is required. Google cannot provide 1-800-Flowers’ certificate on the vendor’s behalf, because it does not have the corresponding private key. Additionally, Google cannot, and should not be able to, sign content using the private key that corresponds to 1-800-Flowers’ certificate.

The inability to use original content URLs with AMP posed some serious issues. First, the google.com/amp URL prefix can strip URLs of their meaning. To the frustration of publishers, their content is no longer directly attributed to them by a URL (let alone a certificate). The publisher can no longer prove the integrity and authenticity of content served on their behalf.

Second, for web browsers the lack of a publisher’s URL can call the integrity and authenticity of a cached webpage into question. Namely, there’s no clear way to prove that this response is a cached version of an actual page published by 1-800-Flowers. Additionally, cookies are managed by third-party providers like Google instead of the publisher.

Enter Web Packaging, a collection of specifications for “packaging” website content with information like certificates and their validity. The HTTP signed exchanges specification allows third-party caches to cache and service HTTPS requests with proof of integrity and authenticity.

In the pre-AMP days, people expected to find a webpage’s content at one definitive URL. The publisher, who owns the domain of the definitive URL, would present a visitor with a certificate that corresponds to this domain and contains a public key.

The publisher would use the corresponding private key to sign a cryptographic handshake, which is used to derive shared symmetric keys that are used to encrypt the content and protect its integrity.

The visitor would then receive content encrypted and signed by the shared key.

The visitor’s browser then uses the shared key to verify the response’s signature and, in turn, the authenticity and integrity of the content received.

With services like AMP, however, online content may correspond to more than one URL. This introduces a problem: while only one domain actually corresponds to the webpage’s publisher, multiple domains can be responsible for serving a webpage. If a publisher allows AMP services to cache and serve their webpages, they must be able to sign their content even when AMP caches serve it for them. Only then can AMP-cached content prove its legitimacy.

HTTP signed exchanges directly address the problem of extending publisher signatures to services like AMP. This IETF draft specifies how publishers may sign an HTTP request/response pair (an exchange). With a signed exchange, the publisher can assure the integrity and authenticity of a response to a specific request even before the client makes the request. Given a signed exchange, the publisher authorizes intermediates (like Google’s AMP Cache) to forward the exchanges; the intermediate responds to a given request with the corresponding response in the signed HTTP request/response pair. A browser can then verify the exchange signature to assert the intermediate response’s integrity and authenticity.

This is like handing out an answer key to a quiz signed by the instructor. Having a signed answer sheet is just as good as getting the answer from the teacher in real time.

An HTTP signed exchange is generated by the following steps.First, the publisher uses MICE (Merkle Integrity Content Encoding) to provide a concise proof of integrity for the response included in the exchange. To start, the response is split into blocks of some record size bits long. Take, for example, a message ABCD, which is divided into record-size blocks A, B, C, and D. The first step to constructing a proof of integrity is to take the last block, D, and compute the following:

proof(D) = SHA-256(D || 0x0)

This produces proof(D). Then, all consequent proof values for blocks are computed as follows:

proof(C) = SHA-256(C || proof(D) || 0x1)
proof(B) = SHA-256(B || proof(C) || 0x1)
proof(A) = SHA-256(A || proof(B) || 0x1)

The generation of these proofs build the following tree:

      proof(A)
         /\
        /  \
       /    \
      A    proof(B)
            /\
           /  \
          /    \
         B    proof(C)
                /\
               /  \
              /    \
             C    proof(D)
                    |
                    |
                    D

As such, proof(A) is a 256-bit digest that a person who receives the real response should be able to recompute for themselves. If a recipient can recompute a tree head value identical to proof(A), they can verify the integrity of the response they received. In fact, this digest plays a similar role to the tree head of a Merkle Tree, which is recomputed and compared to the presented tree head to verify the membership of a particular node. The MICE-generated digest is stored in the Digest header of the response.

Next, the publisher serializes the headers and payloads of a request/response pair into CBOR (Concise Binary Object Representation). CBOR’s key-value storage is structurally similar to JSON, but creates smaller message sizes.

Finally, the publisher signs the CBOR-encoded request/response pair using the private key associated with the publisher’s certificate. This becomes the value of the sig parameter in the HTTP signed exchange.

The final HTTP signed exchange appears like the following:

sig=*MEUCIQDXlI2gN3RNBlgFiuRNFpZXcDIaUpX6HIEwcZEc0cZYLAIga9DsVOMM+g5YpwEBdGW3sS+bvnmAJJiSMwhuBdqp5UY=*;  
integrity="digest/mi-sha256";  
validity-url="https://example.com/resource.validity.1511128380";  
cert-url="https://example.com/oldcerts";  
cert-sha256=*W7uB969dFW3Mb5ZefPS9Tq5ZbH5iSmOILpjv2qEArmI=*;  
date=1511128380; expires=1511733180

Services like AMP can send signed exchanges by using a new HTTP response format that includes the signature above in addition to the original response.

When this signature is included in an AMP-cached response, a browser can verify the legitimacy of this response. First, the browser confirms that the certificate provided in cert-url corresponds to the request’s domain and is still valid. It next uses the certificate’s public key, as well as the headers and body values of request/response pair, to check the authenticity of the signature, sig. The browser then checks the integrity of the response using the given integrity algorithm, digest/mi-sha256 (aka MICE), and the contents of the Digest header. Now the browser can confirm that a response provided by a third party has the integrity and authenticity of the content’s original publisher.

After all this behind-the-scenes work, the browser can now present the original URL of the content instead of one prefixed by google.com/amp. Yippee to solving one of AMP’s most substantial pain points!

From the overview above, the process of generating an HTTP signed exchange is clearly involved. What if there were a way to automate the generation of HTTP signed exchanges and have services like AMP automatically pick them up? With Cloudflare Workers… we found a way you could have your HTTP origin exchange cake and eat it too!

We have already implemented HTTP signed exchanges for one of our customers, 1-800-Flowers. Code deployed in a Cloudflare Worker is responsible for fetching and generating information necessary to create this HTTP signed exchange.

This Worker works with Google AMP’s automatic caching. When Google’s search crawler crawls a site, it will ask for a signed exchange from the same URL if it initially responds with Vary: AMP-Cache-Transform. Our HTTP signed exchange Worker checks if we can generate a signed exchange and if the current document is valid AMP. If it is, that Vary header is returned. After Google’s crawler sees this Vary header in the response, it will send another request with the following two headers:

AMP-Cache-Transform: google
Accept: application/signed-exchange;v=b2

When our implementation sees these header values, it will attempt to generate and return an HTTP response with Content-Type: application/signed-exchange;v=b2.

Now that Google has cached this page with the signed exchange produced by our Worker, the requested page will appear with the publisher’s URL instead of Google’s AMP Cache URL. Success!

If you’d like to see HTTP signed exchanges in action on 1-800-Flowers, follow these steps:

1. Install/open Chrome Beta for Android. (It should be version 71+).

2. Go to goo.gl/webpackagedemo.

3. Search for “Christmas greens.”

4. Click on the 1-800-Flowers link -- it should be about 3 spots down with the AMP icon next to it. Along the way to getting there you should see a blue box that says "Results with the AMP icon use web packaging technology." If you see a different message, double check that you are using the correct Chrome Beta.An example of AMP in action for 1-800-Flowers:

Visiting 1-800 Flowers through AMP with HTTP signed exchange

Phew. There’s clearly a lot of infrastructure for publishers to build for distributing AMP content. Thankfully Cloudflare has one of the largest networks in the world, and we now have the ability to execute JavaScript at the edge with Cloudflare Workers. We have developed a prototype Worker that generates these exchanges, on the fly, for any domain. If you’d like to start experimenting with signed exchanges, we’d love to talk!

Soon, we will release this as a Cloudflare Worker application to our AMP customers. We’re excited to bring a better AMP experience to internet users and advance the Web Packaging standard. Stay tuned!

Web Packaging is not simply a technology that helps fix the URL for AMP pages, it’s a fundamental shift in the way that publishing works online. For the entire history of the web up until this point, publishers have relied on transport layer security (TLS) to ensure that the content that they send to readers is authentic. TLS is great for protecting communication from attackers but it does not provide any public verifiability. This means that if a website serves a specific piece of content to a specific user, that user has no way of proving that to the outside world. This is problematic when it comes to efforts to archive the web.

Services like the Internet Archive crawl websites and keep a copy of what the website returns, but who’s to say they haven’t modified it? And who’s to say that the site didn’t serve a different version of the site to the crawler than it did to a set of readers? Web Packaging fixes this issue by allowing sites to digitally sign the actual content, not just the cryptographic keys used to transport data. This subtle change enables a profoundly new ability that we never knew we needed: the ability to record and archive content on the Internet in a trustworthy way. This ability is something that is lacking in the field of online publishing. If Web Packaging takes off as a general technology, it could be the first step in creating a trusted digital record for future generations to look back on.

Excited about the future of Web Packaging and AMP? Check out Cloudflare Ampersand to see how we're implementing this future.

Cloudflare has been a long time supporter of AMP, an open-source markup language 1.5 billion web pages are using to accelerate their mobile web performance. Cloudflare runs Ampersand, the only alternative to Google’s AMP cache, and earlier this year we launched Accelerated Mobile Links, a way for sites on Cloudflare to open external links on their site in AMP format, as well as Firebolt, leveraging AMP to speed up ad performance.

One of the biggest challenges developers face in converting their web pages to AMP is testing their AMP pages for valid AMP syntax before deploying. It's not enough to make the templates work at dev time, you also need to validate individual pages before they’re published.

Imagine, for example, a publishing company where content creators who are unfamiliar with AMP are modifying pages. Because the AMP markup language is so strict, one person adding an interactive element to a page can all of a sudden break the AMP formatting and stop the page from validating.

We wanted to make it as easy as possible to move webpages and sites to AMP so we built an AMP linter API for developers to check that their AMP pages are formatted correctly, even before they are deployed.

To check if a webpage’s AMP markup is correct, just send the AMP page to the endpoint URL Removed like this:

curl URL REMOVED/amp.usatoday.com/story/82055560/
{
  "source": "http://amp.usatoday.com/story/82055560/", 
  "valid": true, 
  "version": "1488238516283"
}

The API has options to send just the markup content, or point the linter to the live site. To send a file, add the --data-binary flag:

curl -X POST --data-binary @amp_page.html -H 'Content-Type: text/html; charset=UTF-8' URL REMOVED

If you send an AMP page with invalid AMP syntax, the message returned will tell you exactly what breaks your AMP page, and will point you to the specific place in the AMP reference where you can see the implementation guide for the broken element.

curl -X POST --data-binary @invalid_amp.html -H 'Content-Type: text/html; charset=UTF-8' URL REMOVED
{
  "errors": [
    {
      "code": "MANDATORY_TAG_MISSING", 
      "col": 7, 
      "error": "The mandatory tag 'link rel=canonical' is missing or incorrect.", 
      "help": "https://www.ampproject.org/docs/reference/spec.html#required-markup", 
      "line": 13
    }
  ], 
  "source": "POST", 
  "valid": false, 
  "version": "1485227592804"
}

Here’s a reference in python, and if you want to send html directly instead of a live webpage, replace line two with r = requests.post([URL Removed], data=html)

import requests

u = 'www.bbc.co.uk/news/amp/39192025'
r = requests.get('URL REMOVED' + u)
validation = r.json()
if validation['valid']:
  print u, 'is valid'
else:
  print u, 'failed!'
  for e in validation['errors']: 
    print e

Let us know what you think - you can send us feedback at amp-publisher@cloudflare.com. Whether you embed this tool into your build and continuous integration processes, or into your CMS workflows, we’re excited to hear how you use it.

We protect entire corporate networks, help customers build Internet-scale applications efficiently, accelerate any website or Internet application, ward off DDoS attacks, keep hackers at bay, and can help you on your journey to Zero Trust.

Visit 1.1.1.1 from any device to get started with our free app that makes your Internet faster and safer.

To learn more about our mission to help build a better Internet, start here. If you're looking for a new career direction, check out our open positions.

One vital area of web technology has lagged behind in terms of speed and security: online ads. And consumers have been turning to ad blocking technology to secure and speed up their own web browsing.

Today, Cloudflare is introducing a new product to make web ads secure, fast and safe. That product is Firebolt.

With Firebolt, ad networks can instantly speed up and secure their ads, resulting in happy consumers and better conversion rates.

Firebolt delivers:

Cloudflare's global network of 102 data centers in 50 countries, combined with routing and performance technologies, makes the delivery of online ads to any device up to five times faster.

Adding SSL to ad serving has been challenging for some ad networks. Cloudflare has years of experience providing free, one click SSL for our customers. Firebolt ads are automatically available over SSL with no complex process of getting and maintaining SSL certificates.

Firebolt enables any independent ad network to leverage the new AMP ad format easily. This makes it possible for ads to appear in AMP content served by Google and an increasing number of sites. Firebolt is the only independent way to serve the newly announced AMP for Ads outside of Google’s advertising network.

All ad content delivered by Firebolt for AMP for Ads is cryptographically signed to ensure that it meets the required format and security standards. Signed ads reduce the risk of malware and increase confidence in ads for consumers.

Firebolt ads take advantage of web browser security features including CORS, X-Content-Type-Options and Strict-Transport-Security to ensure the integrity of ads delivered to browsers.

Firebolt takes us one step closer to making the Internet a better place by benefitting everyone in the ad ecosystem, including the consumer.

During a recent test, ad platform TripleLift used Cloudflare's Firebolt to serve AMP ads on Time Inc.'s properties. Ads loaded six times faster and Time Inc. saw 13 percent more revenue relative to traditional ads. “Cloudflare was easy to set up, and we saw an impressive difference in the speed of ad delivery with Firebolt's support for AMP for Ads," said Shaun Zacharia, co-founder and President of TripleLift. "AMP Ads loaded six times faster and were three times lighter than comparable standard ads."

If you are an ad network or publisher, please reach out to firebolt@cloudflare.com to learn more about Firebolt and how Cloudflare can help you monetize the Internet content we all rely on.

In October 2015, the team at Google announced Accelerated Mobile Pages (AMP), a new, open technology to make the mobile web as fast as native apps. Since then, a large number of publishers have adopted AMP. Today, 600 million pages across 700,000 different domains are available in the AMP format.

The majority of traffic to this AMP content comes from people running searches on Google.com. If a visitor finds content through some source other than a Google search, even if the content can be served from AMP, it typically won't be. As a result, the mobile web continues to be slower than it needs to be.

Cloudflare's Accelerated Mobile Links helps solve this problem, making content, regardless of how it's discovered, app-quick. Once enabled, Accelerated Mobile Links automatically identifies links on a Cloudflare customer's site to content with an AMP version available. If a link is clicked from a mobile device, the AMP content will be loaded nearly instantly.

To see how it works, try viewing this post from your mobile device and clicking any of these links:

• TechCrunch: Cloudflare explains how FBI gag order impacted business

• ZDNet: CloudFlare figured out how to make the Web one second faster

• The Register: CloudFlare apologizes for Telia screwing you over

• AMP 8 Ball: Ask The Amp Magic 8-Ball A Yes Or No Question.

  

One of the benefits of Accelerated Mobile Links is that AMP content is loaded in a viewer directly on the site that linked to the content. As a result, when a reader is done consuming the AMP content closing the viewer returns them to the original source of the link. In that way, every Cloudflare customers' site can be more like a native mobile app, with the corresponding increase in user engagement.

For large publishers that want an even more branded experience, Cloudflare will offer the ability to customize the domain of the viewer to match the publisher's domain. This, for the first time, provides a seamless experience where AMP content can be consumed without having to send visitors to a Google owned domain. If you're a large publisher interested in customizing the Accelerated Mobile Links viewer, you can contact Cloudflare's team.

While Google was the initial champion of AMP, the technologies involved are open. We worked closely with the Google team in developing Cloudflare's Accelerated Mobile Links as well as our own AMP cache. Malte Ubl, the technical lead for the AMP Project at Google said of our collaboration:

"Working with Cloudflare on its AMP caching solution was as seamless as open-source development can be. Cloudflare has become a regular contributor on the project and made the code base better for all users of AMP. It is always a big step for a software project to go from supporting specific caches to many, and it is awesome to see Cloudflare’s elegant solution for this."

Cloudflare now powers the only compliant non-Google AMP cache with all the same performance and security benefits as Google.

In the spirit of open source, we're working to help develop updates to the project to address some of publishers' and end users' concerns. Specifically, here are some features we're developing to address concerns that have been expressed about AMP:

• Easier ways to share AMP content using publisher's original domains

• Automatically redirecting desktop visitors from the AMP version back to the original version of the content

• A way for end users who would prefer not to be redirected to the AMP version of content to opt out

• The ability for publishers to brand the AMP viewer and serve it from their own domain

Cloudflare is committed to the AMP project. Accelerated Mobile Links is the first AMP feature we're releasing, but we'll be doing more over the months to come. As of today, Accelerated Mobile Links is available to all Cloudflare customers for free. You can enable it in your Cloudflare Performance dashboard. Stay tuned for more AMP features that will continue to increase the speed of the mobile web.

_{CC BY-SA 2.0 image by David Joyner}

TypeScript is JavaScript with optional types. Here’s a simple example:

// Sends some data to some analytics endpoint
function sendAnalyticsJS(data) {
  if (typeof data.type !== 'string') {
    throw new Error('The `type` property is required')
  }

  navigator.sendBeacon('/beacon', JSON.stringify(data))
}


// Results in run-time error
//    The `type` property is required
sendAnalyticsJS({ foo: 'bar' })

The JavaScript code will result in a run-time error. This is fine if the developer catches it early, but it would be better if the developer were warned as the bug was introduced. Here’s the same code written using TypeScript:

// Describe the shape of the data parameter
interface IAnalyticsData {
  // Type is required
  type: string
  // All other fields are fair game
  [propName: string]: string
}


// We don’t particularly need the data.type check here since
// the compiler will stamp out the majority of those cases.
function sendAnalytics(data: IAnalyticsData) {
  if (typeof data.type !== 'string') {
    throw new Error('The `type` property is required')
  }

  navigator.sendBeacon('/beacon', JSON.stringify(data))
}


// Results in compile-time error:
//   Argument of type '{ foo: string; }' is not assignable to
//   parameter of type 'IAnalyticsData'.
//   Property 'type' is missing in type '{ foo: string; }'.
sendAnalytics({ foo: 'bar' })

These annotations are all optional and the more you add, the more the compiler can help you. Compiling the TypeScript version results in code equivalent to the first example. The only difference is that the developer is warned about an error while writing the code.

With TypeScript, JavaScript developers are given powerful tools that aid the development of applications, large and small. Anders Hejlsberg, lead architect of C# and core dev for TypeScript, describes the language as, “JavaScript that scales.”

Using TypeScript means you can:

• Interactively explore library interfaces from your text editor

• Enjoy useful auto-completion

• Use good refactoring tools

• Navigate your codebase via the ontology that describes it (by that, I mean jumping to class and interface definitions, modules, etc. from individual instances/references)

• And most importantly to this post, generate documentation that’s tightly coupled to your codebase.

_{The screenshot above is of the generated documentation from a TypeScript project at Cloudflare.}

The amount of work required to annotate source code with JSDoc comments is comparable to adopting TypeScript annotations. However, JSDoc comments are not tightly coupled to the codebase, so when the code changes, an independent change of the JSDoc comment is also required. Contrast to TypeScript where the structure is gleaned directly from the source. Here’s a side-by-side comparison between JSDoc and TypeScript:

/**
 * A class representing a point
 * @class  Point
 */
class Point {
  /**
   * Create a point.
   * @param {number} x - The x value.
   * @param {number} y - The y value.
   */
  constructor(x, y) {
    /**
     * The x coordinate
     * @name  Point#x
     * @type {number}
     */
    this.x = x
    /**
     * The y coordinate
     * @name  Point#y
     * @type {number}
     */
    this.y = y
  }


  /**
   * Get the x value.
   * @return {number} The x value.
   */
  getX() {
    return this.x
  }


  /**
   * Get the y value.
   * @return {number} The y value.
   */
  getY() {
    return this.y
  }


  /**
   * Convert a string containing two comma-separated numbers into a point.
   * @param {string} str - The string containing two comma-separated numbers.
   * @return {Point} A Point object.
   */
  static fromString(str) {
    const args = str.split(',').map(arg => +arg)
    return new Point(args[0], args[1])
  }
}

TypeScript

/** Class representing a point. */
class Point {
  /** The x coordinate */
  public x: number
  /** The x coordinate */
  public y: number


  /**
   * Create a point.
   * @param x - The x value.
   * @param y - The y value.
   */
  constructor(x: number, y: number) {
    this.x = x
    this.y = y
  }


  /**
   * Get the x value.
   */
  getX() {
    return this.x
  }


  /**
   * Get the y value.
   */
  getY() {
    return this.y
  }

  /**
   * Convert a string containing two comma-separated numbers into a point.
   * @param str - The string containing two comma-separated numbers.
   */
  static fromString(str: string): Point {
    const args = str.split(',').map(arg => +arg)
    return new Point(args[0], args[1])
  }
}

The above code sample was taken from the JSDoc documentation and adapted for use with TypeScript.

The annotations for TypeScript are much more compact, they’re syntax-highlighted, and most importantly, if something is wrong, the compiler lets us know. Long-form descriptions of things are still made in comments, but the type information has been moved into language semantics.

The downside to adopting TypeScript is the large amount of work required to fit the build tools into your current processes. However, we won’t focus on the nitty-gritty details of build tools since the ecosystem is rapidly changing.

At Cloudflare, we use a tool called TypeDoc to help build documentation. It’s set up such that documentation-generation is on watch and will re-build on codebase changes. Anybody hacking on the project will always have up-to-date docs at localhost:3000/docs.

If you’re using TypeScript 2.x, use the following command to install TypeDoc for your project:

npm install --save-dev https://github.com/DatenMetzgerX/typedoc/tarball/typescript-2-build

Otherwise, for prior versions of TypeScript, you can install straight from

npm install --save-dev typedoc

From within your project directory, run the following command:

# Change the --out flag to wherever you’d like the output to be stored
./node_modules/.bin/typedoc --out dist/docs --mode modules .

You should see a bunch of HTML documents generated. One for each class and module.

dist/docs
├── assets
│   ├── css
│   │   ├── main.css
│   │   └── main.css.map
│   ├── images
│   │   ├── icons.png
│   │   ├── icons@2x.png
│   │   ├── widgets.png
│   │   └── widgets@2x.png
│   └── js
│       ├── main.js
│       └── search.js
├── classes
│   ├── _src_my_class.html
│   └── ...
├── globals.html
├── index.html
├── interfaces
│   ├── _src.my_interface.html
└── modules
    ├── _src_my_module_.html
    └── ...

I wanted to build something akin to Lodash’s documentation (a beautiful single page API reference with examples and links to source code). Luckily, you can use TypeDoc’s --json flag to produce a set of useful descriptions of your codebase in JSON format.

./node_modules/.bin/typedoc --json dist/docs.json --mode modules

Note: In order to use the --json flag, you’ll need to setup a proper tsconfig.json for your TypeScript project.

With this high-level, structured description of our code base, we can render any HTML we’d like with a few scripts and a templating language like Handlebars. Here’s a simple script to render a list of code base modules:

const fs = require('fs')
const hbs = require('handlebars')
const project = require('./dist/docs.json')


// The HTML template to use for our simple docs
const tmpl = `
<!DOCTYPE HTML>
<html>
  <head>
    <title>My Project Documentation</title>
  </head>
  <body>
    <h1>Modules</h1>
    <ul>
    {{#each project.children}}
      <li>{{this.name}}</li>
    {{/each}}
    </ul>
  </body>
</html>
`


// Compile the template with handlebars using our project
// object as context key
const result = hbs.compile(tmpl)({ project })


fs.writeFileSync('dist/docs.html', result)

While this means that there is a lot of work up front to create a template that suits the needs of this particular code base, I hope to use the same infrastructure for TypeScript projects at Cloudflare moving forward.

TypeDoc gets us halfway there. It provides a structured and automated way to create reference material that is always in sync with our codebase; but we can do more than reference material. Suppose you’re writing a getting-started.md file. You might say something like this:

To get started, call the `viewer.init()` method.

Since we’re using TypeDoc and Handlebars, we can assume we have all the information necessary to actually link to the source code. That might look something like this:

{{!-- Pull the AMPViewer class into scope --}}
{{#Class "AMPViewer"}}
{{!-- Pull the init member from AMPViewer into scope --}}
{{#Member "init"}}
{{!-- Link viewer.init(...) to its location in the source code --}}
{{!-- Also, if the function signature of the .init() method ever changes, --}}
{{!-- it will be reflected here --}}
To get started, call the
`viewer.[init({{> signature signature=signatures.0}})]({{getSourceURL this.sources.0}})`
{{/Member}}
{{/Class}}

While the above looks arcane, it’s just Markdown and Handlebars. The template contains a block helper called Class that will pull the AMPViewer class object into the current scope. Then using the AMPViewer class, we pull the init member into the current scope. We use the {{> signature}} partial to pretty-print the function’s signature and the getSourceUrl helper to link to this method in the source code.

If the source code changes, our docs update too.

Over next couple of months, we’ll be open sourcing the tools we’ve created to generate our documentation. We’ll also open source the theme shown in this post so you can generate docs without worrying about the styling. We hope to create a rich TypeScript ecosystem and to have fantastic documentation for all of our projects.

If you’re thinking of generating documentation by annotating your source, use TypeScript instead and enjoy the benefits.