Origami Frontend Components & Services

Readme: polyfill-service active

Makes web development less frustrating by selectively polyfilling just what the browser needs. Use it on your own site, or as a service.

For usage information see the hosted service, which formats and displays the service API documentation located in the docs folder.

Build
Status
MIT licensed

Requirements

Running the polyfill service requires a few tools:

Running locally

Clone the project to your system:

git clone git@github.com:Financial-Times/polyfill-service.git

Change into the project directory:

cd polyfill-service

Install the dependencies:

npm install

Build the polyfill sources and start the server, rebuilding and restarting whenever any changes are made to the project:

npm run dev

Configuration

You can configure the Polyfill service using environment variables. In development, configurations are set in .env. In production, these are set through Heroku config.

Testing

The tests are split into tests for the service and tests for the polyfills. The polyfill tests require BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY to be configured, view the configuration section for more information.

npm run test           # run service tests and polyfill tests on a small set of browsers
npm run test-node    # run the service tests
npm run ci             # run the service tests and polyfills tests on a large set of browsers

We run the tests on CircleCI. npm run ci must pass before we merge a pull request.

Real User Monitoring

We have shipped experimental support for using RUM to monitor feature support and performance in browsers. This involves a number of parts, all activated by the presence RUM_MYSQL_DSN and RUM_BEACON_HOST env vars:

Because this requires a fair amount of orchestration, we recommend only enabling it for the FT hosted version. If you want to run the service yourself, you can opt out of this RUM feature by not setting a RUM_MYSQL_DSN or RUM_BEACON_HOST.

Routes

Deploying Lambda

All the bits of the RUM solution are deployed as part of our existing deployment workflow except the Lambda functions, which require Apex. To deploy the Lambda functions:

  1. Create the following 7 environment variables in your local environment or the .env file in the project root: RUM_MYSQL_DSN, RUM_AWS_ACCESS_KEY, RUM_AWS_SECRET_KEY, a second copy of each of these suffixed with _QA, and RUM_AWS_REGION. FT devs can get the correct values for these variables from Heroku config or Lastpass.
  2. Run npm run deploy-lambda or npm run deploy-lambda -- --env=prod as appropriate
  3. If this is the first time you've deployed the function to this AWS profile, you then need to configure the function in the AWS UI:
    • Set up a trigger to invoke the function whenever a file is written to the appropriate S3 bucket

polyfill.io CDN

The Financial Times and Fastly host a public version of this service on polyfill.io.

Release process

  1. Test the release candidate with the npm run compatgen task to generate an updated compatibility table. - npm run compatgen && git commit docs/assets/compat.json -m 'update compat.json'
  2. Tag the commit using npm's version command. - npm version {premajor | preminor | prepatch} if creating a new RC, or npm version prerelease if you already have an active premajor, preminor or prepatch.
  3. Publish to npm under the next dist-tag. - npm publish --tag next
  4. Push the commits and tags to the git remote. - git push origin master --tags
  5. Deploy to QA. - npm run deploy
  6. Announce the release on twitter
  7. Wait some number of days for feedback (usually 7 days). If necessary, make fixes and return to step 1
  8. Tag the commit/package using npm's version command, using the same semver level as you used for the pre versions. - npm version {major | minor | patch}
  9. Publish to npm under the latest dist-tag. - npm publish
  10. Push the commits and tags to the git remote. - git push origin master --tags
  11. Deploy to production. - npm run promote

Monitoring

We use Graphite and Grafana to keep track of application metrics. You can view requests, bundle build duration, cache hit ratios, and memory usage. It's important after a deploy to make sure we haven't unexpectedly had an impact on these.

We also use Pingdom to track uptime. You should get notifications if you're a member of the Origami team.

Library

API reference

The Polyfill service can also be used as a library in NodeJS projects. To do this:

  1. Add this repo as a dependency in your package.json
    e.g. npm install polyfill-service --save
  2. Rebuild your project using npm install
  3. Use the API from your code

getPolyfillString(options) (method)

Returns a promise of a polyfill bundle string. Options is an object with the following keys:

Flags that may be applied to polyfills are:

Example:

require('polyfill-service').getPolyfillString({
    uaString: 'Mozilla/5.0 (Windows; U; MSIE 7.0; Windows NT 6.0; en-US)',
    minify: true,
    features: {
        'Element.prototype.matches': { flags: ['always', 'gated'] },
        'modernizr:es5array': {}
    }
}).then(function(bundleString) {
    console.log(bundleString);
});

getPolyfills(options) (method)

Returns a promise of a set of features which are configured to be applied in browsers with the specified user agent string.
Options is an object with the following keys:

Example:

require('polyfill-service').getPolyfills({
    uaString: 'Mozilla/5.0 (Windows; U; MSIE 7.0; Windows NT 6.0; en-US)',
    features: {
        'Element.prototype.matches': { flags: ['always', 'gated'] },
        'modernizr:es5array': {}
    }
}).then(function(polyfillSet) {
    console.log(polyfillSet);
});

listAllPolyfills() (method)

Return a promise of an array all the polyfills as an array of strings. This list corresponds to directories and subdirectories in the /polyfills directory.

Example:

require('polyfill-service').listAllPolyfills();

License

Except where indicated in selected polyfill config files, the polyfill service codebase is licensed under the terms of the MIT license. Contributors must accept our contribution terms.

Switch component view

GitHub Repository

Help & Support

Check the polyfill-service documentation if you haven't already. It's maintained directly by the Origami team so if you have any questions we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com