While the project can still be used for reference, the reality is that it has aged and no longer reflects best practices. To make this clear, the project is now archived.

Typescript Node API Starter (Archived)

Live App Demo: https://node-api-starter-angular-app.experiments.explabs.io
Live API: https://node-api-starter.experiments.explabs.io/v1/hello

A boilerplate for Node.js APIs designed for app consumption, written in Typescript.

This project has two purposes:

1. Provide a boilerplate for modern Node.js API development with the following requirements
   • fully configured development environment
   • created to be used primarily as a backend for SPAs or PWAs
   • have all the most common requirements already implemented (authentication, database integration, CI integration and more)
2. Serve as a reference for various implementations from CD with CircleCI to putting it all together with an example app.

You can find the Angular App source code here https://github.com/feredean/node-api-starter-angular-app

Table of contents

• Requirements
  • Quick start
  • Fancy start
• Getting started
• Environment variables
• Deployment
  • Prerequisites
  • Deploying to kubernetes
  • CircleCI
• Project structure
• Build scripts
• Import path quirks
• Debugging
• Testing
  • Integration tests and jest
  • Configure Jest
  • Running tests
  • Linting
  • VSCode Extensions
• Dependencies
  • production
  • development
• Resources
• Related projects
• License

Requirements

There are two ways to go about handling requirements. You can either follow the quick start path where you dump all the dependencies in your system or you can go down the fancy setup that will give you more flexibility in the future by using nvm and docker.

Quick start

• Install Node.js
• Install MongoDB
• Install VS Code

Fancy start

• Install Node Version Manager
• Configure nvm Shell Integration (highly recommend setting up zsh together with oh my zsh). Once you set it up it will automatically change the node version if the project has a .nvmrc file.
• Install docker
• Run MongoDB in a docker container docker run -d --name mongo-dev -p 27017:27017 mongo:4.0

Getting started

Set VSCode's Typescript import module specifier for the workspace to relative for more information have a look here

# Get the latest snapshot
git clone --depth=1 https://github.com/feredean/node-api-starter.git <project_name>

# Change directory
cd <project_name>

# Install dependencies
npm install

# Build the project
npm run build

# Copy the .env.example contents into the .env
cat .env.example > .env

# Run (development mode) the API on port 9100
npm run watch

To build the project in VS Code press cmd + shift + b. You can also run tasks using the command pallet (cmd + shift + p) and select Tasks: Run Task > npm: start to run npm start for you.

Finally, navigate to http://localhost:9100/v1/hello and you now have access to your API

Environment variables

For how environment variables are imported and exported have a look in src/config/secrets. Here you can also change the requiredSecrets or the way mongoURI is constructed if for example you wish to use username/password when connecting to mongo in the development environment.

Name	Description
	The session secret is used to sign the JWT tokens
SESSION_SECRET	A quick way to generate a secret: node -e "console.log(require('crypto').randomBytes(256).toString('base64'));"
	The mongo host and port are not necessarily taken from the .env file they can be provided by the deployment environment such as k8s
MONGO_HOST	mongo host
MONGO_PORT	mongo port
MONGO_DATABASE	name of the database
MONGO_USERNAME	mongo user - not used for development, required for production
MONGO_PASSWORD	mongo user's password - not used for development, required for production
	Facebook credentials used for sign in with Facebook - currently not implemented
FACEBOOK_ID	Facebook ID
FACEBOOK_SECRET	Facebook Secret
	Sendgrid credentials used by the nodemailer package in forgot/reset password functionality
SENDGRID_USER	Sendgrid account user name
SENDGRID_PASSWORD	Sendgrid account password
	AWS user used for uploading files to s3 with AmazonS3FullAccess Policy
AWS_ACCESS_KEY_ID	AWS Access key ID
AWS_ACCESS_KEY_SECRET	AWS Access key secret
	This will be used to create a REGEX that will block origins that don't match
CORS_REGEX	use localhost:\d{4}$ for development and domain\.tld$ for production

Deployment

The example in this project is built around the existence of a kubernetes cluster. You can easily change to your infrastructure of choice by changing the deploy step in .circleci/config.yml to pull the docker image wherever you need it.

# pull the image from docker hub and deploy it to the k8s cluster
deploy:
  docker:
    - image: feredean/circleci-kops:0.1.0
  environment:
    IMAGE_NAME: feredean/node-api-starter
    KOPS_STATE_STORE: s3://k8s-explabs-io-state-store
  steps:
    - run:
        name: Deploy to k8s cluster
        command: |
          # Ensure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set in the project's env vars
          kops export kubecfg --name k8s.explabs.io
          kubectl set image deploy/node-api-starter node-api-starter=$IMAGE_NAME:$CIRCLE_SHA1

Prerequisites

Kubernetes

Depending on your cloud provider of choice you can fairly quickly set up a managed, production-ready environment for deploying containerized applications.

• Google's GKE
• Amazon's EKS
• Microsoft's AKS

This project is deployed on a cluster set up with kops on aws spot instances. If there is interest I plan on going more in depth on this subject and provide a walk-through.

MongoDB

If you're like me and don't want the headache and uncertainty of managing your own production database take a look at mongodb's atlas. If you feel up to the task there are some kubernetes projects like KubeDB that can be of use.

Deploying to Kubernetes

First you need to have an .env.prod file that has all the secrets that will be used in production. A node-starter secret needs to be created, it is used by the API deployment.

kubectl create secret generic node-starter --from-env-file=.env.prod

Notice that in .kubernetes/deployment.yaml the environment is loaded from the node-starter secret

envFrom:
  - secretRef:
      name: node-starter

Finally you need to create the kubernetes deployment, service and optionally the horizontal pod autoscaler that can later be paired with the cluster autoscaler. To do this simply run the following:

kubectl create -f .kubernetes/deployment.yaml

If somehow a deadly bug has managed to make its way past the test suite and got deployed to production where it's wreaking havoc you need to run following command:

kubectl rollout undo deployment <your deployment name>

This will instantly roll back the deployment to the previous one.

CircleCI

To integrate with CircleCI:

1. Go to CircleCI and create an account

2. Link your project

3. Add the needed environment variables to run the test

   # Used to connect to the kubernetes cluster
   AWS_ACCESS_KEY_ID
   AWS_SECRET_ACCESS_KEY
   
   # Used for publishing the image
   DOCKERHUB_PASS
   DOCKERHUB_USERNAME
   

4. Make master branch a protected branch require ci/circleci: test check before merging from feature branches. Once a PR is merged into master CircleCI will automatically build, test and deploy the new version of the API.

Congratulations! You how have an API set up and ready to embrace the CD workflow!

Project structure

Name	Description
.circleci	Contains CircleCI settings for continuous deployment
.kubernetes	Contains kubernetes configuration for running the app