Origami Frontend Components & Services

Readme: origami-build-service

Use the Origami Build Service to include Origami components in your project with a <script> and <style> tag, no build step required.

To learn more about using the Origami Build Service refer to the API reference and Origami Build Service Tutorial.

Table Of Contents


Running Origami Build Service requires Node.js and npm.

Running Locally

Before we can run the application, we'll need to install dependencies:

npm install

Run the application in development mode with

make run-dev

Now you can access the app over HTTP on port 8080: http://localhost:8080/


We configure Origami Build Service using environment variables. In development, configurations are set in a .env file. In production, these are set through Heroku config. Further documentation on the available options can be found in the [Origami Service documentation][service-options].

Required everywhere

Required in Heroku



The tests are split into unit tests, integration tests, and an old suite of tests that we're migrating. To run tests on your machine you'll need to install Node.js and run make install. Then you can run the following commands:

make test              # run all the tests
make test-unit         # run the unit tests
make test-integration  # run the integration tests

You can run the unit tests with coverage reporting.

make test-unit-coverage verify-coverage

The code will also need to pass linting on CI, you can run the linter locally with:

make verify

We run the tests and linter on CI, you can view [results on CI][ci]. make test and make verify must pass before we merge a pull request.

You can run the integration tests against a URL by setting a HOST environment variable to the URL you want to test. This is useful for testing a Heroku application after it is deployed, which we do on CI.

HOST="https://www.example.com" make test-integration


The production (EU/US) and QA applications run on Heroku. We deploy continuously to QA via [CI][ci], you should never need to deploy to QA manually. We use a Heroku pipeline to promote QA deployments to production.

You can promote either through the Heroku interface, or by running the following command locally:

make promote

You may need to clear cdn cache for the release to take immediate effect. For example when updating documentation.

Cache Purge

First, change the hostname in your request to origami-build-service-eu.herokuapp.com. If your update does not appear, an old version is cached on the file system. Clear this by restarting the Heroku dynos:

heroku restart --app origami-build-service-eu

If your change does appear then the old result may be cached by our CDN. You'll need to wait for a while, or clear the CDN cache. To clear CDN cache login to Fastly and find the www.ft.com Fastly service. Clear a specific URL (e.g. for a documentation update) or one or more of the following surrogate keys:

Documentation Cache Purge

All documentation pages e.g. /v2, /v2/api, /v2/migration, /v3/, /v3/api, /url-updater:

V3 API Cache Purge

All bundle pages e.g. /v3/bundles/css:

All fonts i.e. /v3/font:

All demo pages e.g. /v3/demo:

V2 API Cache Purge

All bundle pages e.g. /v2/bundles/css:

All file pages i.e. /v2/files:

All demo pages e.g. /v2/demos:



We use Splunk to store and query our application and CDN log files. Using Splunk we can answer many questions, such as: which product is using our services the most; which components are not being requested (good candidates to deprecate).

Here is an example query which was used to find out if our o-big-number component was being requested.

Here is an example query which shows the last hour of logs from our CDN.


We've outlined some common issues that can occur when running the Build Service:

What do I do if memory usage is high?

For now, restart the Heroku dynos:

heroku restart --app origami-build-service-eu

If this doesn't help, then a temporary measure could be to add more dynos to the production applications, or switch the existing ones to higher performance dynos.

What if I need to deploy manually?

If you really need to deploy manually, you should only do so to QA. Production deploys should always be a promotion from QA.

You'll need to provide an API key for change request logging. You can get this from the Origami LastPass folder in the note named Change Request API Keys. Now deploy to QA using the following:

CR_API_KEY=<API-KEY> make deploy

What do I do if my updated component is not appearing in bundles?

This is most likely due to the heavy caching we use. See Cache Purge.


The Financial Times has published this software under the MIT license.

active Origami v1 (Bower)
Switch component view

GitHub: origami-build-service

Help & Support

Check the origami-build-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: #origami-support
Email: origami.support@ft.com