Before you start developing in AMP, check out these resources:
- CONTRIBUTING.md has details on various ways you can contribute to the AMP Project.
- If you're developing in AMP, you should read the Contributing code and Contributing features sections.
- The Ongoing participation section has details on various ways of getting in touch with others in the community including email and Slack.
- If you are new to open source projects, Git/GitHub, etc., check out the Tips for new open source contributors which includes information on getting help and finding your first bug to work on.
- The Getting Started Quick Start Guide has installation steps and basic instructions for one-time setup, how to build AMP & run a local server and how to test AMP.
For most developers the instructions in the Getting Started Quick Start Guide will be sufficient for building/running/testing during development. This section provides a more detailed reference.
The Quick Start Guide's One-time setup has instructions for installing Node.js, Yarn, and Gulp which you'll need before running these commands.
Command | Description |
---|---|
gulp [1] |
Runs "watch" and "serve". Use this for standard local dev. |
gulp dist [1] |
Builds production binaries. |
gulp dist --fortesting [1] |
Indicates the production binaries are used for local testing. Without this ads, tweets and similar use cases are expected to break locally when using minified sources. |
gulp lint |
Validates against Google Closure Linter. |
gulp lint --watch |
Watches for changes in files, Validates against Google Closure Linter. |
gulp lint --fix |
Fixes simple lint warnings/errors automatically. |
gulp build [1] |
Builds the AMP library. |
gulp build --fortesting [1] |
Builds the AMP library and will read the AMP_TESTING_HOST environment variable to write out an override AMP_CONFIG. |
gulp build --css-only [1] |
Builds only the embedded css into js files for the AMP library. |
gulp clean |
Removes build output. |
gulp css |
Recompile css to build directory. |
gulp extensions |
Build AMP Extensions. |
gulp watch [1] |
Watches for changes in files, re-build. |
gulp test [1] |
Runs tests in Chrome. |
gulp test --verbose [1] |
Runs tests in Chrome with logging enabled. |
gulp test --nobuild |
Runs tests without re-build. |
gulp test --watch [1] |
Watches for changes in files, runs corresponding test(s) in Chrome. |
gulp test --watch --verbose [1] |
Same as "watch" with logging enabled. |
gulp test --saucelabs [1] |
Runs test on saucelabs (requires setup). |
gulp test --safari [1] |
Runs tests in Safari. |
gulp test --firefox [1] |
Runs tests in Firefox. |
gulp test --files=<test-files-path-glob> [1] |
Runs specific test files. |
gulp serve |
Serves content in repo root dir over http://localhost:8000/. Examples live in http://localhost:8000/examples/ |
npm run ava [1] |
Run node tests for tasks and offline/node code using ava. |
[1] On Windows, this command must be run as administrator.
For manual testing build AMP and start the Node.js server by running gulp
.
The content in the examples
directory can be reached at: http://localhost:8000/examples/
For each example there are 3 modes:
/examples/abc.html
points to prod. This file would not reflect your local changes./examples/abc.max.html
points to your local unminified AMP. You want to use this during normal dev./examples/abc.min.html
points to a local minified AMP. This is closer to the prod setup. Only available after runninggulp dist --fortesting
.
AMP ships with a local proxy for testing production AMP documents with the local JS version.
For any public AMP document like: http://output.jsbin.com/pegizoq/quiet
You can access is with the local JS at
- normal sources: http://localhost:8000/max/output.jsbin.com/pegizoq/quiet
- minified: http://localhost:8000/min/output.jsbin.com/pegizoq/quiet
When accessing min
urls make sure you run gulp dist
with the --fortesting
flag so that we do not strip out the localhost code paths. (We do some
code elimination to trim down the file size for the file we deploy to production)
If the origin resource is on HTTPS, the URLs are http://localhost:8000/max/s/output.jsbin.com/pegizoq/quiet and http://localhost:8000/min/s/output.jsbin.com/pegizoq/quiet
If you are working on AMP 4 Ads (A4A), you can use the local A4A envelope for testing local and production AMP documents with the local JS version.
A4A can be run either of these two modes:
- Friendly iframe mode: http://localhost:8000/a4a/...
- 3p iframe mode: http://localhost:8000/a4a-3p/...
The following forms are supported:
- local document: http://localhost:8000/a4a[-3p]/examples/animations.amp.max.html
- proxied document with normal sources: http://localhost:8000/a4a[-3p]/max/output.jsbin.com/pegizoq/quiet
- proxied document with minified sources: http://localhost:8000/a4a[-3p]/min/output.jsbin.com/pegizoq/quiet
When accessing min
urls make sure you run gulp dist
with the --fortesting
flag so that we do not strip out the localhost code paths. (We do some
code elimination to trim down the file size for the file we deploy to production)
If the origin resource is on HTTPS, the URLs are http://localhost:8000/a4a[-3p]/max/s/output.jsbin.com/pegizoq/quiet and http://localhost:8000/a4a[-3p]/min/s/output.jsbin.com/pegizoq/quiet
Notice that all documents are assumed to have a "fake" signature. Thus, this functionality is only available in the
localDev
mode.
Additionally, the following query parameters can be provided:
width
- the width of theamp-ad
(default "300")height
- the height of theamp-ad
(default "250")offset
- the offset to push theamp-ad
down the page (default "0px"). Can be used to push the Ad out of the viewport, e.g. usingoffset=150vh
.
If you are working on AMP In-a-box Ads, you can use the local in-a-box envelope for testing local and production AMP documents with the local JS version.
Make sure to run gulp with --with_inabox
flag.
The following forms are supported:
- local document: http://localhost:8000/inabox/examples/animations.amp.max.html
- proxied document with normal sources: http://localhost:8000/inabox/max/output.jsbin.com/pegizoq/quiet
- proxied document with minified sources: http://localhost:8000/inabox/min/output.jsbin.com/pegizoq/quiet
Additionally, the following query parameters can be provided:
width
- the width of theiframe
(default "300")height
- the height of theiframe
(default "250")offset
- the offset to push theiframe
down the page (default "0px"). Can be used to push the Ad out of the viewport, e.g. usingoffset=150vh
.
For testing documents on arbitrary URLs with your current local version of the AMP runtime we created a Chrome extension.
In general local testing (i.e. gulp test
) and the automatic test run on Travis that happens when you send a pull request are sufficient. If you want to run your tests across multiple environments/browsers before sending your PR you can use Sauce Labs.
To run the tests on Sauce Labs:
-
Create a Sauce Labs account. If you are only going to use your account for open source projects like this one you can sign up for a free Open Sauce account. (If you create an account through the normal account creation mechanism you'll be signing up for a free trial that expires; you can contact Sauce Labs customer service to switch your account to Open Sauce if you did this accidentally.)
-
Set the
SAUCE_USERNAME
andSAUCE_ACCESS_KEY
environment variables. On Linux add this to your.bashrc
:export SAUCE_USERNAME=<Sauce Labs username> export SAUCE_ACCESS_KEY=<Sauce Labs access key>
You can find your Sauce Labs access key on the User Settings page.
-
Install the Sauce Connect Proxy.
-
Run the proxy and then run the tests:
# start the proxy sc # after seeing the "Sauce Connect is up" msg, run the tests gulp test --saucelabs
-
It may take a few minutes for the tests to start. You can see the status of your tests on the Sauce Labs Automated Tests dashboard. (You can also see the status of your proxy on the Tunnels dashboard.
It's much faster to debug with local build (gulp
+ http://localhost:8000/
). In Chrome you can use DevTools port forwarding. However, iOS Safari does not give a similar option. Instead, you can use ngrok. Just download the ngrok binary for your platform and run it like this:
ngrok http 8000
Once started, the ngrok will print URLs for both http
and https
. E.g. http://73774d8c.ngrok.io/
and https://73774d8c.ngrok.io/
. These URLs can be used to debug on iOS and elsewhere.
For deploying and testing local AMP builds on HEROKU , please follow the steps outlined in this document.
In the meantime you can also use our automatic build on Heroku link, which is normally built with latest head on master branch (please allow delay). The first time load is normally slow due to Heroku's free account throttling policy.
To correctly get ads and third party working when testing on hosted services
you will need set the AMP_TESTING_HOST
environment variable. (On heroku this
is done through
heroku config:set AMP_TESTING_HOST=my-heroku-subdomain.herokuapp.com
)
3p/ - Implementation of third party sandbox iframes. ads/ - Modules implementing specific ad networks used in build/ - (generated) intermediate generated files build-system/ - build infrastructure builtins/ - tags built into the core AMP runtime *.md - documentation for use of the builtin *.js - source code for builtin tag contributing/ - docs for people contributing to the AMP Project css/ - default css dist/ - (generated) main JS binaries are created here. This is what gets deployed to cdn.ampproject.org. dist.3p/ - (generated) JS binaries and HTML files for 3p embeds and ads. This is what gets deployed to 3p.ampproject.net. docs/ - documentation about AMP examples/ - example AMP HTML files and corresponding assets extensions/ - plugins which extend the AMP HTML runtime's core set of tags spec/ - The AMP HTML Specification files src/ - source code for the AMP runtime test/ - tests for the AMP runtime and builtins testing/ - testing infrastructure
In general we support the 2 latest versions of major browsers like Chrome, Firefox, Edge, Safari and Opera. We support desktop, phone, tablet and the web view version of these respective browsers.
Beyond that the core AMP library and builtin elements should aim for very wide browser support and we accept fixes for all browsers with market share greater than 1 percent.
In particular, we try to maintain "it might not be perfect but isn't broken"-support for the Android 4.0 system browser and Chrome 28+ on phones.
We also recommend scanning the spec. The non-element part should help understand some of the design aspects.