Koa / Vue.js SPA Template App
Switch branches/tags
Nothing to show
Clone or download


Koa / Vue.js SPA Template App

This app is a template application using Koa for a REST/JSON API server and Vue.js for a web client.

screen recording 2017-06-10 at 04 12 pm

Overview of Stack

  • Server
    • Koa
    • PostgresSQL
    • TypeScript
    • TypeORM (data-mapper ORM)
    • routing-controllers (decorated, class-based controllers in Koa)
    • Docker used for development PostgresSQL database and MailHog server
  • Client
    • Vue.js
    • Single-file components (.vue)
    • TypeScript
    • Webpack for asset bundling and HMR (Hot Module Replacement)
    • Bootstrap CSS
    • Fetch API for REST requests
  • Testing
    • Mocha
    • Chai
    • TypeScript
    • MailHog for development email delivery
  • DevOps
    • Ansible playbook for provisioning (Nginx reverse proxy, SSL via Let's Encrypt, PostgresSQL backups to S3)
    • Ansible playbook for deployment

Development Setup

  1. Install the following:
  2. Run npm install && npm start
  3. Open browser and navigate to http://localhost:5000.


npm install

When first cloning the repo or adding new dependencies, run this command. This will:

  • Install Node dependencies from package.json

npm start

To start the app for development, run this command. This will:

  • Run docker-compose up to ensure the PostgreSQL and MailHog Docker images are up and running
  • Run dotnet watch run which will build the app (if changed), watch for changes and start the web server on http://localhost:5000
  • Run Webpack dev middleware with HMR

npm run migration:create [name]

Creates a new migration file in api/db/migrations/. Migrations will be run each time the app starts (controlled with api/config/default.yml:autoMigrationsRun)

npm test

This will run the 2 test suites in test/.

  • unit - The unit tests are located in test/unit/
  • integration - The integration tests are located in test/integration/

npm run provision:production

Before running this script, you need to create an ops/config.yml file first. See the ops README for instructions.

This will run the ops/provision.yml Ansible playbook and provision hosts in ops/hosts inventory file. This prepares the hosts to recieve deployments by doing the following:

  • Install Nginx
  • Generate a SSL certificate from Let's Encrypt and configure Nginx to use it
  • Install Node.js
  • Install Supervisor (will run/manage the Node.js/Koa app)
  • Install PostgreSQL
  • Setup a cron job to automatically backup the PostgresSQL database, compress it, and upload it to S3.
  • Setup UFW (firewall) to lock everything down except inbound SSH and web traffic
  • Create a deploy user, directory for deployments and configure Nginx to serve from this directory

npm run deploy:production

Before running this script, you need to create a ops/config.yml file first. See the ops README for instructions.

This script will:

  • Build release Webpack bundles
  • Package the Koa application
  • Run the ops/deploy.yml Ansible playbook to deploy this app to hosts in /ops/config.yml inventory file. This does the following:
  • Copies the build assets to the remote host(s)
  • Creates config/local-production.yml the appsettings.json file with PostgresSQL credentials specified in ops/hosts file and the app URL (needed for JWT tokens)
  • Restarts the app so that changes will be picked up

Development Email Delivery

This template includes a MailHog Docker image so that when email is sent during development (i.e. new user registration), it can be viewed in the MailHog web interface at http://localhost:8025/.

Visual Studio Code config

This project has Visual Studio Code tasks and debugger launch config located in .vscode/.


  • Command+Shift+B - Runs the "build" task which builds the api/ project and outputs to api/build/
  • Command+Shift+T - Runs the "test" task which runs the tests.

Debug Launcher

With the following debugger launch configs, you can set breakpoints and have full debugging support in Visual Studio Code

  • Debug api/ - Runs api (Node.js/Koa app) app with the VSCode debugger
  • Debug test/integration/ - Runs the integration test suite with the VSCode debugger
  • Debug test/unit/ - Runs the unit test suite with the VSCode debugger