Skip to content
KOAN (Koa, Angular, Node, Mongo) starter kit for full-stack JavaScript web development.
JavaScript HTML CSS
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE Initial commit Feb 11, 2014


Build Status

KOAN Stack is a boilerplate that provides a starting point for full stack JavaScript Web development with Koa, AngularJS, and Node.js along with MongoDB and WebSockets. A summary of tech stack:

  • Client: AngularJS and Bootstrap. Client side is fully static and CDN ready. All client packages are located at client\bower_packages.
  • Server: Koa for RESTful API serving on Node.js. ES6 async/await functions all the way!
  • WebSockets along with JSON-RPC is used for real-time client-server communication and browser sync.
  • OAuth 2 is used for social authentications. Instead of auth cookies, we use JWT along with HTML5 local storage.
  • Grunt tasks are used to facilitate development and testing.
  • MongoDB for persistence.

Live Example

Browse the live KOAN example on which is a Facebook like real-time sharing app.

Getting Started

Make sure that you have Node.js v7.6 or higher (for Node <7.6, use v1.6 release), and MongoDB v2 or higher (running on the default port 27017) installed on your computer. To get started with KOAN stack, do following:

git clone --depth 1
cd koan
npm install
npm start

Your application should run on the 3000 port so in your browser just go to http://localhost:3000. If you want to run tests, simply type:

npm test


All configuration is specified in the /server/config directory, particularly the config.js file. Here you can hook up any social app keys if you want integration with Twitter, Facebook, or Google.

Heroku Deployment


Procfile and app.json are making this repo readily available for Heroku deployment. You can start by clicking the above button.


You can run all the tests with npm test. Tests are run with:

  • Client (unit): Jasmine + Karma (Angular default)
  • Client (e2e): Jasmine + Protractor (Angular default)
  • Server: Mocha/SuperTest/Should (Koa default)

See /test/server/users.js for an example.


Client side is entirely based on the official: Angular Seed. Server side simply utilizes generally accepted Koa middleware and Node.js best practices.

The Name

The project name is an acronym for Koa, Angular, and Node. It also is the name for a Zen Buddhist riddle used to focus the mind during meditation and to develop intuitive thinking.




Screenshots from the demo app, in case Heroku app is down.

Login page:

Login Page

User home page:

Home Page

You can’t perform that action at this time.