@financial-times/n-gage

Make it so next

Stats

StarsIssuesVersionUpdatedCreatedSize
@financial-times/n-gage
9108.3.22 months ago4 years agoMinified + gzip package size for @financial-times/n-gage in KB

Readme

n-gage CircleCI

n-gage is in every FT.com project and gives a standard set of make tasks and the ngage CLI to help set up, build and deploy projects.

Requirements

  • Node version defined by .nvmrc (run command nvm use to switch your local Node version to the one in this file).
  • Vault

Installation

git clone git@github.com:Financial-Times/n-gage.git
cd n-gage
make install

Development

Testing

In order to run the tests locally you'll need to run:

make test

Install from NPM

npm install --save-dev --no-package-lock @financial-times/n-gage

Usage

Create a new Makefile file with the following:

# This task tells `make` how to 'build' n-gage. It npm installs n-gage, and
# Once that's done it overwrites the file with its own contents - this
# ensures the timestamp on the file is recent, so `make` won't think the file
# is out of date and try to rebuild it every time
node_modules/@financial-times/n-gage/index.mk:
    npm install --no-save @financial-times/n-gage
    touch $@

# If, by the end of parsing your `Makefile`, `make` finds that any files
# referenced with `-include` don't exist or are out of date, it will run any
# tasks it finds that match the missing file. So if n-gage *is* installed
# it will just be included; if not, it will look for a task to run
-include node_modules/@financial-times/n-gage/index.mk

Make tasks

Task Description
a11y Run automated accessibility tests
build Build the repository
build-production Build the repository for production
clean Git clean the repository
deploy-assets Uploads static files such as CSS and JS to S3
deploy-production Deploy staging to production eu and us apps. Also scale down canary app
deploy-canary Deploy canary app to staging
deploy-staging Deploy the app to staging
deploy-promote Promote the staging app to production
deploy Deploy the app to heroku
.env Downloads environment variables from Vault
fix-lintspaces Autofix common lintspaces issues
help Show this help message
init Clean the repository and start from a fresh build
install Install dependencies and copy common dotfiles
test-review-app Create and test a review app on heroku.

To override custom environment variables when running nht configure, add:
REVIEW_APP_CONFIGURE_OVERRIDES="NODE_ENV=branch,OTHER_VAR=something"
to the Makefile
smoke Run smoke tests on the local or review app, by setting the TEST_URL environment variable
verify Check files for linting errors
watch Watch for static asset changes

Git hooks

By default n-gage will automatically configure some git hooks to be run by Husky. If you want to disable this behaviour, add the following line to the very top of your Makefile:

DISABLE_GITHOOKS=true

CLI

This tool helps you to obtain configuration for your project.

$ ngage get-config

get environment variables from Vault

Options:
  --version     Show version number                            [boolean]
  --help        Show help                                      [boolean]
  --app                                     [default: "ft-next-article"]
  --env                           [choices: "dev", "prod", "ci", "test"]
  --custom-env
  --filename                                           [default: ".env"]
  --format               [choices: "simple", "json"] [default: "simple"]
  --team                                               [default: "next"]

For example, to fetch the ci environment variables:

$ ngage get-config --env ci --filename .env-ci --format json
# {
#   "AWS_ACCESS_KEY_ID": "...",
#   "AWS_SECRET_ACCESS_KEY": "...",
#     ...
# }

There is an additional --team flag that lets you specify a team if not next (must match Vault path).

$ ngage get-config --team myteam

FT User Sessions

To get FTSession and FTSession_s environment variables to be populated with up-to-date session tokens from test users, add the following environment variables to your development and/or continuous-integration configs in the Vault:

Variable Description
TEST_SESSIONS_URL url to next-test-sessions-lambda
TEST_SESSIONS_API_KEY api_key for the lambda
TEST_USER_TYPES user types to get the tokens for (options: premium, standard, expired)

As a result of this, {USER_TYPE}_FTSession and {USER_TYPE}_FTSession_s environment variables will be populated in the .env file.

Multiple user types can be specified in the TEST_USER_TYPES variable.

Example

If you set TEST_USER_TYPES environment variable to premium,standard, these variables will be populated in the .env file: PREMIUM_FTSession, PREMIUM_FTSession_s, STANDARD_FTSession, STANDARD_FTSession_s

Pa11y environment variables

Pa11y configuration has been moved to n-config-pa11y. You can follow the instructions there on how to setup Pa11y. Alternativelly, n-gage will keep this original setup until migration is complete.

Variable Description
PA11Y_WAIT The time to wait before running tests in milliseconds
PA11Y_ROUTE_EXCEPTIONS api_key for the lambda
PA11Y_ROUTE_HEADERS user types to get the tokens for (options: premium, standard, expired)
PA11Y_HIDE A CSS selector to hide elements from testing, selectors can be comma separated
PA11Y_VIEWPORTS Set viewports for puppeteer (w1024h768,w375h667)

Deployment variables

These variables should be declared in the Makefile to set up deployment tasks using Heroku pipelines.

Variable Description
VAULT_NAME [Required] The name of the app in vault. Should also be the name in package.json eg, ft-next-search-page
HEROKU_APP_STAGING [Required] The name of the Heroku staging app eg, ft-next-search-page-staging
HEROKU_APP_EU [Required] The main Heroku app or the EU Heroku app if it is a multi-region app eg, ft-next-search-page-eu for multi region or ft-next-video-page for single region
HEROKU_APP_US [Optional] The US Heroku app. Only needed if it is a multi region app
HEROKU_APP_CANARY [Optional] The canary Heroku app. Only needed if there is a canary app eg, ft-next-preflight-canary-eu
HEROKU_APP_CANARY_SCALE [Optional] Canary apps only. Specify the number of web dynos for the canary app. If not specified, it will use the HEROKU_APP_EU scale configuration
REVIEW_APP_CONFIGURE_OVERRIDES [Optional] Override environment variables for the review apps. By default it is NODE_ENV=branch, so to add new ones add REVIEW_APP_CONFIGURE_OVERRIDES="NODE_ENV=branch,OTHER_VAR=something"

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.