Awesome Open Source
Awesome Open Source



Build Status codecov Package dependencies Codacy Badge

Koa 2 and GraphQL server that just works™. We've climbed the mountain of boilerplate for you, so you don't have to.


  • koa2 - write stuff in middleware
  • babel - use latest ES6/7 features today. why wait?
  • passport.js - easy authentication
  • knex.js - documentation is better than sequelize
  • GraphQL - it's the way to go
  • Jest - don't let tests get in your way
  • ramda - please don't use lodash or underscore
  • prettier - don't worry about formatting…
  • flowtype - get your types right

Getting started

Make sure you have Docker installed as PostgreSQL is run on the docker container.

git clone -o k2 -b master --single-branch example-api

cd example-api                  # Change current directory to the newly created one
yarn install                    # Install required packages via yarn
cp .env.sample .env             # Configuration on development mode is done via dotenv
yarn migrate:latest             # Run database migrations
yarn seed:run                   # Add some seed data
yarn start:dev                  # Start the server in development mode

By default the API server starts on port 5000, http://localhost:5000.


┌── .env.sample                 # Sample .env file loaded into process.env
├── docker-compose.yml          # Auxiliary services such as postgresql via docker
├── knexfile.js                 # Configuration for knex.js
├── migrations/                 # Database migrations. See below for more info
├── seeds/                      # Database seeds. See below for more info
├── tests/                      # Integration tests using supertest
├── sqlite3/                    # SQLite3 database location
└── src/
    ├── db.js                   # DB instance used by the app and/or models
    ├── models/                 # ORM models written in ES6 classes
    ├── middleware/             # Custom middleware to be used by modules
    ├── modules/                # Route-Controller pair for koa2
    │   ├── auth/               # Sample /authenticate module
    │   ├── graphql/            # GraphQL
    │   └── index.js            # Don't touch this
    ├── passport.js             # Passport.js configuration using passport-local
    ├── DataLoader.js           # Data fetching layer for GraphQL
    ├── schema.js               # GraphQL schema
    └── types/                  # GraphQL types


K2 uses Facebook Jest so you can add a directory named __tests__ at any level and start writing tests.

Root level tests directory is reserved for integration tests using supertest. Currently requires you to run the database server via docker-compose: see above.

yarn test                 # Run all tests including unit and integration tests
yarn test:unit            # Only run unit tests inside src/ directory
yarn test:integration     # Only run integration tests inside tests/ directory
yarn test:coverage        # Generate coverage report. Also travis default


This is a standard Node.js version 8.0+ application. You can deploy it to anywhere you like including, but not limited to:

Deploying to now is super simple if you're using SQLite3 (default). Just run:


AWS ElasticBeanstalk

Simply create a version of AWS EB with Node version 8.0.1 and deploy. I personally have travis CI deploy it via a eb script.

  • TODO: Sample .ebextensions/
  • Database is already configured to prefer RDS_{HOSTNAME,DB_NAME,USERNAME,PASSWORD} connection information

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (70,281
nodejs (3,798
graphql (1,071
postgresql (743
jest (285
starter-kit (179
koa2 (114
passport (57
flowtype (53