widget-sales-api

A simple Express server that returns clients and sales of widgets. There's a client app for it which has its own GitHub repo: widget-sales-react.

Contents:

• Dependencies
• Development
• Tests
• Code Linting
• Deployment
• Related Links

Dependencies

Install Yarn via Homebrew on Mac:

brew update
brew install yarn 1.3.2

For other operating systems see the Yarn installation docs.

Clone the repo and run yarn install:

git clone git@github.com:albertkawmi/widget-sales-api.git
cd widget-sales-api
yarn install

NOTE: Yarn creates a yarn.lock file, locking dependency versions so that installs run consistently across machines. At project start, latest stable version of Yarn was 1.3.2. If you have any problems installing or running dependencies, please try this version.

Development

Run the server locally:

yarn dev

This will listen on the default port 80 (which is probably undesirable). You can configure this in the .env file in root project directory:

echo PORT=4000 > .env

.env is .gitignored so it will not be committed to source control. This means you'll need to add it on each machine you work on.

After yarn dev Nodemon will listen for file changes and restart the local server automatically.

Debugging

The --inspect flag is used to enable debugging. You can use Chrome Dev tools for this:

1. Start the dev server with yarn dev
2. Navigate to chrome://inspect
3. Click the 'inspect' link for your server under 'Remote Target'

A new window will open with the Chrome debugger.

Run locally in production mode

yarn dev uses Nodemon, debugging and sets the environment variable NODE_ENV=development. If you wish to test the server locally as if it were in production use:

yarn start

Tests

Jest is used as a test runner and tests are written using the Supertest library. Supertest will run the app on port 4242 for testing (this is configurable in package.json).

The following commands are available:

• yarn test runs tests once
• yarn test:watch runs tests in watch mode for TDD
• yarn test:coverage runs tests once, with coverage report

Code Linting

yarn eslint

ESLint is used for linting and can be configured in the .eslintrc file. Run yarn eslint to check from the command line (or use an ESLint plugin for your code editor).

Deployment

Zeit Now.sh is used for cloud infrastructure and hosting. All Now deployments in their free plan will be given a subdomain with a hash under now.sh (see example link below). These URLs can be used as a staging step after local development.

For production, a friendly alias (without the hash) can be redirected to the new instance URL. This redirect means zero downtime. It also means deployments can be reverted by simply reassigning the alias to a previous instance.

Staging

yarn deploy:staging

This will run ESLint, all tests and then deploy to a URL like https://widget-sales-api-xxxxx.now.sh

Production

yarn deploy:production

This will run ESLint, all tests and then deploy to the production alias https://widget-sales-api.now.sh

The alias widget-sales-api is connected to my credentials. You can modify this to anything you like in package.json and Now will allow you to deploy it (you may need to confirm your email address if it's your first time using Now, then it will store credentials on your machine.)

Reverting

Since the deployment is simply an alias change, it is easy to revert:

1. Run yarn now ls to see a list of running instances
2. Copy the URL for the instance you wish to revert to
3. Run yarn now alias the-new-instance-xxxxx.now.sh widget-sales-api

NOTE: if you are on the free plan of now.sh you can only have a few instances running concurrently. To remove instances, run the yarn now ls command and then use yarn now rm the-instance-to-remove.now.sh to destroy old instances.

Related links

• This API server in production
• The client-side app in production
• GitHub repo for the client-side app
• My blog
• Zeit Now.sh
• Express.js
• Jest
• Supertest
• Nodemon
• Yarn