Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
amp-prototyper
Advanced tools
Readme
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.
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.
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.
To run the script, you may choose one of the following methods:
Run the script directly with npx:
npx amp-prototyper [URL]
URL
- URL to the page to convert.Install amp-prototyper package.
git clone https://github.com/jonchenn/amp-prototyper.git
cd amp-prototyper
yarn install
Then, run the script.
./amp-prototyper [URL]
./amp-prototyper [URL]
Required arguments:
URL
- URL to the page to convert.--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.--fullPageScreenshot=(true|false*)
- tWhether to save full-page screenshots.--compareScreenshots=(true|false*)
- Whether to compare original site with converted.--customHost=HOST
- Use a custom host name when updating relative asset URLs.--port=PORT_NUMBER
- Port number to use to compare before and after (defaults to 8080)--verbose
- Display AMP validation errors.# Amplify a page and generate results in /output folder.
./amp-prototyper https://thinkwithgoogle.com
# Amplify a page and generate results in /output/test folder.
./amp-prototyper https://thinkwithgoogle.com --output=test
# Amplify a page with customized steps.
./amp-prototyper https://thinkwithgoogle.com --steps=custom/mysteps.js
# Amplify a page and display AMP validation details.
./amp-prototyper https://thinkwithgoogle.com --verbose
# Amplify a page and generate screenshots with specific Device.
./amp-prototyper https://thinkwithgoogle.com --device='Pixel 2'
# Amplify a page and display browser.
./amp-prototyper https://thinkwithgoogle.com --headless=false
# Amplify a page and compare original site with converted.
./amp-prototyper https://thinkwithgoogle.com --compareScreenshots=true
# Amplify a page that served from localhost and generate results with correct absolute URLs for assets.
./amp-prototyper https://thinkwithgoogle.com --customHost=https://example.com
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. (If localhost has trouble connecting to the port, add the --port flag with a different port number)
# 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.
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]-validation.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.
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
Check the image comparsion to see visual differences in the original URL and AMP HTML
Remove the watermark in the AMP HTML and review the code for additional changes/AMP validation error fixes
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
<[string]> Step name.actions
<[Array]<Action>> actions to execute.skip
<[boolean]> Whether to skip this step.Common properties of an action:
actionType
<string]> Action type.log
<[string]> Message output of this action.waitAfterLoaded
<[number]> Wait for a specific milliseconds after the page loaded.You can also use the following EnvVars in the steps configuration.
$URL
<[string]> The URL from the --url
parameter.$HOST
<[string]> The host derived from the URL.$DOMAIN
<[string]> 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".
Set an attribute to a specific element.
selector
<[string]> target element.attribute
<[string]> attribute to ad.value
<[string]> the attribute value.Remove an attribute to a specific element.
selector
<[string]> target element.attribute
<[string]> attribute to remove.Use Regex to find and replace in the DOM.
selector
<[string]> target element.regex
<[string]> Regex string to match.replace
<[string]> Replace matches with this string.Remove an attribute to specific elements based on AMP validation errors.
selector
<[string]> target element.Use Regex to find and replace in the DOM based on AMP validation errors.
selector
<[string]> target element.ampErrorRegex
<[string]> Regex string to match for AMP validation errors.regex
<[string]> Regex string to match.replace
<[string]> 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.
Use Regex to find and replace in the DOM. If not found, insert to the destination element.
selector
<[string]> target element.regex
<[string]> Regex string to match.replace
<[string]> Replace matches with this string.Insert a string to the bottom of the destination element. E.g. adding a string to the bottom of the .
selector
<[string]> target element.value
<[string]> the string to insert.destSelector
<[string]> destination element.Move elements to the bottom of the destination element. E.g. moving all
to the bottom of the .
selector
<[string]> target element.destSelector
<[string]> destination element.Append a string right after a specific element.
selector
<[string]> target element.value
<[string]> the string to append.Collect all external CSS and append a <style>
tag with inline CSS.
selector
<[string]> target element to append the CSS.value
<[string]> the string to append.excludeDomains
<[Array]<[string]>> the array of excluded domains. E.g. ['examples.com'] excludes all CSS loaded from examples.com
.minify
<[boolean]> whether to minify CSS.attributes
<[Array]<[string]>> add attributes when appending <style>
tag.Remove unused CSS using clean-css and purifycss.
selector
<[string]> target element.value
<[string]> the string to append.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
<[ActionObject]> the action object itself.sourceDom
<[DOM document]> the raw DOM document object before rendering, as in the View Source in Chrome.page
<[puppeteer Page object]> The page object in puppeteer.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
Since AMP-prototyper is built with Puppeteer to fetch a page content, some sites may treat this as a crawler or bot, and thus block the access. You may see a different content (e.g. 404 page or timeout) than the regular page content.
The blocking logic usually resides in the web hosting servers. Hence, there's no easy way to overcome. However, you can try the following options:
Some sites may treat puppeteer activities as crawler if it runs in the headless mode. You can try running with headless off, and puppeteer will show the browser window like browsing by a real user.
# Amplify a page without headless mode.
./amp-prototyper http://127.0.0.1:8080 --headless=false
Another option to bypass crawler-protection is to download the page and serve the page from a local web server. (E.g. http-server)
For example, you can save the index page of ThinkWithGoogle.com and serve it locally. It's recommended to copy the page source directly instead of using a browser's Save function to avoid unexpected artifacts by the browser.
Since the host is now localhost
instead of its original host (www.thinkwithgoogle.com), all relative asset paths would incorrectly end up with localhost. Hence, we need to pass --customHost
to restore its true remote host for asset URLs.
# Assuming that the index page is saved to ./tmp/web/index.html
npm i http-server -g
http-server ./tmp/web -p 3000
In a new terminal:
./amp-prototyper http://127.0.0.1:3000 --customHost=https://www.thinkwithgoogle.com
FAQs
This Node.js-based script is a prototyping tool that automatically converts a HTML page to a [Accelerated Mobile Page (AMP)](https://amp.dev) to demonstrate performance gains with AMP. It follows [the general guideline of converting HTML to AMP](https://a
The npm package amp-prototyper receives a total of 3 weekly downloads. As such, amp-prototyper popularity was classified as not popular.
We found that amp-prototyper demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer 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.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.