ampproject/amp-toolbox

AMP Toolbox

A collection of AMP tools making it easier to publish and host AMP pages. The following tools are part of this project:

• amp-cache-url: a javascript library for translating origin URLs to the AMP Cache URL format.
• amp-cache-list: a javascript library for listing the known AMP Caches.
• amp-cli: a command line version of AMP Toolbox
• amp-cors: a connect/express middleware to automatically add AMP Cors headers.
• amp-linter: a javascript library for linting AMP documents (includes CLI mode).
• amp-optimizer: a javascript library implementing server-side-rendering for AMP pages.
• amp-optimizer-express an express middleware that applies AMP server-side-rendering on the fly.
• amp-optimizer-docker a Docker container that exposes an API for AMP server-side-rendering on the fly.
• amp-runtime-fetch: a javascript library for downloading the AMP runtime.
• amp-runtime-version: a javascript library for querying the current AMP runtime version.
• amp-script-csp: a javascript library for calculating amp-script compatible CSP hashes.
• amp-update-cache: a javascript library for updating AMP documents in AMP Caches.
• amp-validator-rules: a javascript library for querying AMP validator rules.

Development

Setting up your environment

After forking amp-toolbox to your own github org, do the following steps to get started:

# clone your fork to your local machine
git clone https://github.com/your-fork/amp-toolbox.git

# step into local repo
cd amp-toolbox

# install dependencies
npm install

# run tests
npm test

Adding new dependencies

amp-toolbox uses Lerna to manage it's packages. To keep build times low, devDependencies (but not CLI dependencies) must be added to the root package.json file. Runtime dependencies are managed for each package individually.

When adding a new package inside the packages directory, register the package via:

npm run bootstrap

Running Tests

The test suite runs for all packages and must be run from the root directory.

# run tests on node and browser
npm test

# run only in node (fastest)
npm run test:node

# run only in browser
npm run test:browser

Using additional arguments the node tests can generate a coverage report or run only for a specific package.

# generate a coverage report
npm run test:node -- --collectCoverage

# run only tests for AMP Optimizer
npm run test:node -- packages/optimizer

Style & Linting

This codebase adheres to the Google Javascript Styleguide and is enforced using ESLint. ESLint is run as part of the test suite, but you can also explicitly run it via:

# run ESLint
npm run lint

# run ESLint with `--fix` option to automatically fix errors (if possible)
npm run lint:fix

Making a Release

Before publishing a release, make sure to have the lates changes from master and the changelog is up-to-date:

$ npm run changelog

This will print all changes since the previous release. For this to work, all PRs need to be correctly labeled as:

• breaking (💥 Breaking Change)
• enhancement (🚀 Enhancement)
• bug (🐛 Bug Fix)
• documentation (📝 Documentation)
• internal (🏠 Internal)

Copy and prepend the new changes to CHANGELOG.md when you're about to make a release. Don't forget to update the version. Commit the updated changelog and run:

$ npm publish

to publish all changed packages to NPM. Pick the new version according to SemVer.

Contributing

Please see the CONTRIBUTING file for information on contributing to the AMP Project.

License

AMP Toolbox is made by the AMP Project, and is licensed under the Apache License, Version 2.0.