amp-prototyper

This Node.js-based script is a prototyping tool that automatically converts a HTML page to a Accelerated Mobile Page (AMP) to demonstrate performance gains with AMP. It follows the general guideline of converting HTML to AMP.

TL;DR

• The goal is to showcase the advantages of AMP in page load performance.
• It generates a converted AMP HTML, a screenshot, and AMP validation errors for each step.
• It automatically converts a HTML page to AMP with pre-defined steps. You can customize the steps for specific scenarios.

What is amp-prototyper

The main goal is to minimize the effort of creating a prototype AMP page from a canonical HTML page, such as adding AMP boilerplate, removing custom Javascript, making all CSS inline, etc. The output of this tool includes converted AMP, the screenshot, and AMP validation errors for each conversion step.

This script uses puppeteer to load and render pages.

Non-scope

This tool doesn't aim to create production-ready AMP pages from any arbitrary HTML pages. If your goal is to create high-quality AMP pages for production, please follow the general guideline of converting HTML to AMP.

Getting started

Run the following to run the script locally.

git clone https://github.com/jonchenn/amp-prototyper.git
cd amp-prototyper
yarn install

Usage

./amp-prototyper [URL]

Required arguments:

• URL - URL to the page to convert.

Options

• --steps=FILE - Path to the custom steps JS file. If not defined, it will use ./steps/default-steps.js
• --output=FILE - Path to the output file.
• --device=DEVICE_NAME - Use specific device name for screenshots.
• --headless=(true|false) - Whether to show browser.
• --verbose - Display AMP validation errors.

Examples:

# Amplify a page and generate results in /output folder.
./amp-prototyper http://127.0.0.1:8080

# Amplify a page and generate results in /output/test folder.
./amp-prototyper http://127.0.0.1:8080 --output=test

# Amplify a page with customized steps.
./amp-prototyper http://127.0.0.1:8080 --steps=custom/mysteps.js

# Amplify a page and display AMP validation details.
./amp-prototyper http://127.0.0.1:8080 --verbose

# Amplify a page and generate screenshots with specific Device.
./amp-prototyper http://127.0.0.1:8080 --device='Pixel 2'

# Amplify a page and display browser.
./amp-prototyper http://127.0.0.1:8080 --headless=false

Test with a sample HTML.

You can also run a sample HTML with following:

# Run a localhost web server using http-server.
yarn sample

This opens up a localhost web server at http://127.0.0.1:8080 by default that serves test/index.html. This is a quick and simple HTML page to test amp-prototyper. You can run the following to see how amp-prototyper works.

# Amplify the page at localhost and output in sample/ folder.
./amp-prototyper http://127.0.0.1:8080 --output=sample

Then, check out the ./output/sample, and you will see a list of output files.

Output of each step

When you run the script, it follows predefined steps, either default steps at src/default-steps.js, or customized steps.

You can amplify a HTML page with default steps:

# Amplify a page with default steps.
./amp-prototyper http://127.0.0.1:8080

Or run amplify a page with customized steps:

# Amplify a page with customized steps.
./amp-prototyper http://127.0.0.1:8080 --steps=custom/mysteps.js

At each step, it executes a set of actions and writes the files below to the output/ folder:

• output-step-[STEP_ID].html - the modified HTML.
• output-step-[STEP_ID].png - the screenshot after this step.
• output-step-[STEP_ID]-log.txt (only with --verbose) - AMP validation errors from console output.

If you don't specify --output, it uses the domain from the given URL as the name of the output folder.

Verify your output

You can run the following command to run a simple web server locally to serve your output files.

yarn output

Open up the localhost URL with a browser. For example: http://127.0.0.1:8080

Customize steps

Structure of steps

You can check out the default steps at src/default-steps.js.

Each step follows the structure below.

{
  name: 'Name of the step',
  actions: [{
    skip: false,
    log: 'Log output for this action',
    actionType: 'replace',
    selector: 'html',
    regex: '<div(.*)>(.*)</div>',
    replace: '<span$1>$2</span>',
  }, {
    ...
  }],
},

Step properties:

• name

  - Step name.

• actions<Array<Action>> - actions to execute.

• skip

  - Whether to skip this step.

Common properties of an action:

• actionType

  - Action type.

• log

  - Message output of this action.

• waitAfterLoaded

  - Wait for a specific milliseconds after the page loaded.

Environment Variables

You can also use the following EnvVars in the steps configuration.

• $URL

  - The URL from the --url parameter.

• $HOST

  - The host derived from the URL.

• $DOMAIN

  - The domain derived from the URL.

For example, you have a step like below:

{
  name: 'Name of the step',
  actions: [{
    log: 'Log output for this action',
    actionType: 'replace',
    selector: 'html',
    regex: '<div(.*)>(.*)</div>',
    replace: '<span$1>$HOST</span>',
  }],
},

While running the script with https://example.com, it replaces """$HOST""" with "https://example.com".

Supported actions:

setAttribute

Set an attribute to a specific element.

• log

  - Message output of this action.

• waitAfterLoaded

  - Wait for a specific milliseconds after the page loaded.

replace

Use Regex to find and replace in the DOM.

• selector

  - target element.

• regex

  - Regex string to match.

• replace

  - Replace matches with this string.

replaceBasedOnAmpErrors

Use Regex to find and replace in the DOM based on AMP validation errors.

• selector

  - target element.

• ampErrorRegex

  - Regex string to match for AMP validation errors.

• regex

  - Regex string to match.

• replace

  - Replace matches with this string.

For example, in a specific step it has the following AMP validation errors.

line 61, col 4: The attribute 'onclick' may not appear in tag 'button'.
line 70, col 4: The tag 'custom-tag' is disallowed.

To replace the

in the body based on the AMP validation result, you can have the following step:

{
  name: 'Convert disallowed tags to <div> based on AMP validation result.',
  actions: [{
    log: 'Change tags to <div>',
    actionType: 'replaceBasedOnAmpErrors',
    selector: 'body',
    ampErrorRegex: 'The tag \'([^\']*)\' is disallowed',
    regex: '<($1)((.|[\\r\\n])*)</$1>',
    replace: '<div data-original-tag="$1" $2</div>',
  }],
}

This step matches the AMP validation result with ampErrorRegex. Then it replace the regex with the capturing group #1 from ampErrorRegex. In this case, the regex becomes:

<(custom-tag)((.|[\\r\\n])*)</custom-tag>

Finally, it uses the revised regex to replace the content with replace value.

replaceOrInsert

Use Regex to find and replace in the DOM. If not found, insert to the destination element.

• selector

  - target element.

• regex

  - Regex string to match.

• replace

  - Replace matches with this string.

insert

Insert a string to the bottom of the destination element. E.g. adding a string to the bottom of the .

• selector

  - target element.

• value

  - the string to insert.

• destSelector

  - destination element.

move

Move elements to the bottom of the destination element. E.g. moving all

to the bottom of the .

• selector

  - target element.

• destSelector

  - destination element.

appendAfter

Append a string right after a specific element.

• selector

  - target element.

• value

  - the string to append.

inlineExternalStyles

Collect all external CSS and append a

<style> tag with inline CSS.

• selector - target element to append the CSS.
• value - the string to append.
• excludeDomains <Array> - the array of excluded domains. E.g. ['examples.com'] excludes all CSS loaded from examples.com.
• minify - whether to minify CSS.
• attributes <Array> - add attributes when appending <style> tag.

removeUnusedStyles

Remove unused CSS using clean-css and purifycss.

• selector - target element.
• value - the string to append.

customFunc

Run the action with a custom function. Example:

  # An action object.
  {
    log: 'Click a button',
    actionType: 'customFunc',
    customFunc: async (action, sourceDom, page) => {
      await page.click('button#summit');
    },
  }],
},

In the custom function, there are three arguments:

• action - the action object itself.
• sourceDom - the raw DOM document object before rendering, as in the View Source in Chrome.
• page - The page object in puppeteer.

Customize steps

To customize your own steps for specific scenarios, create a .js file like below:

module.exports = [
  {
    name: 'Remove unwanted styles',
    actions: [{
      log: 'Remove inline styles in body',
      actionType: 'replace',
      selector: 'body',
      regex: '(<!--)?.*<style[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>.*(-->)?',
      replace: '',
    }, {
      log: 'Remove noscript in body',
      actionType: 'replace',
      selector: 'body',
      regex: '(<!--)?.*<noscript[^<]*(?:(?!<\/noscript>)<[^<]*)*<\/noscript>.*(-->)?',
      replace: '',
    }],
  }, {
    ...
  }
];

Next, run the script with --steps=/path/to/mysteps.js:

# Amplify a page with customized steps.
./amp-prototyper http://127.0.0.1:8080 --steps=/path/to/mysteps.js

Reference

• puppeteer
• clean-css
• purifycss

</style>