hongymagic/k2

Koa2 API template with passport, GraphQL, flowtype, knex and more.

K2

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

Included…

• 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 https://github.com/hongymagic/k2.git 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.

Structure

┌── .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

Testing

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

Deployments

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

• now.sh
• AWS Elastic Beanstalk
• Pretty much anything that runs docker or Node.js

Now.sh

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

now

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

k2's Issues

Implement user creation, signup workflow

• Create a new user
• Validate a new user

100% Test coverage by default

Add more concrete GraphQL example

• Retrieve user (me) information when logged in

Example integration with Auth0

Getting started documentation incorrect at db migrations

Error when running yarn migrate:latest

yarn migrate:latest

yarn migrate:latest v0.21.3
$ knex migrate:latest
sh: knex: command not found
error Command failed with exit code 127.

I think it is missing a yarn install?