Boilerplate and tooling for authoring data API backends with Node.js and GraphQL
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
.circleci Optimize Dockerfile, docker-compose.yml, .circleci/config.yml (#80) Nov 15, 2017
.vscode Group GraphQL schema definitions by business entities Dec 14, 2017
locales Fixed German translations (#31) Apr 18, 2017
migrations Group GraphQL schema definitions by business entities Dec 14, 2017
seeds Group GraphQL schema definitions by business entities Dec 14, 2017
src Force select email (Google Login) (#93) May 21, 2018
tools Group GraphQL schema definitions by business entities Dec 14, 2017
.babelrc Integrate Prettier (#50) Aug 3, 2017
.editorconfig Initial commit Nov 8, 2016
.env Move CREATE EXTENSION to config/postgres-init.sh May 31, 2017
.eslintrc.js Group GraphQL schema definitions by business entities Dec 14, 2017
.flowconfig Group GraphQL schema definitions by business entities Dec 14, 2017
.gitattributes Add .sh to .gitattributes Aug 16, 2017
.gitignore Add settings for VS Code debugger Jul 15, 2017
.prettierignore Do not auto-format pacakge.json with Prettier Dec 1, 2017
.prettierrc Add bracket spacing rule to prettier config (#87) Jan 6, 2018
CONTRIBUTING.md Update project name in copyright messages Dec 24, 2016
Dockerfile Group GraphQL schema definitions by business entities Dec 14, 2017
LICENSE.txt Group GraphQL schema definitions by business entities Dec 14, 2017
README.md Group GraphQL schema definitions by business entities Dec 14, 2017
docker-compose.yml Group GraphQL schema definitions by business entities Dec 14, 2017
package.json Run unit tests in "node" environment Dec 18, 2017
postgres-initdb.sh Remove Nginx; update dependencies; add Tech Stack Aug 30, 2017
yarn.lock Fix yarn.lock Dec 18, 2017

README.md

Node.js API Starter Kit  

Boilerplate and tooling for authoring data API backends with Node.js and GraphQL. It is best suited for developing a GraphQL API endpoint as a standalone (micro)service (demo), backing up web front-ends and/or mobile apps (see React Starter Kit, React Static Boilerplate etc). Please, visit our sponsors:

Hiring


This project was bootstraped with Node.js API Starter Kit (support).

GraphQL Demo
https://graphql-demo.kriasoft.com

Tech Stack

Directory Layout

.
├── /build/                     # The compiled output (via Babel)
├── /locales/                   # Localization resources (i18n)
├── /migrations/                # Database schema migrations
├── /seeds/                     # Scripts with reference/sample data
├── /src/                       # Node.js application source files
│   ├── /emails/                # Handlebar templates for sending transactional email
│   ├── /routes/                # Express routes, e.g. /login/facebook
│   ├── /schema/                # GraphQL schema type definitions
│   ├── /utils/                 # Utility functions (mapTo, mapToMany etc.)
│   ├── /app.js                 # Express.js application
│   ├── /Context.js             # Data loaders and other context-specific stuff
│   ├── /db.js                  # Database access and connection pooling (via Knex)
│   ├── /email.js               # Client utility for sending transactional email
│   ├── /errors.js              # Custom errors and error reporting
│   ├── /passport.js            # Passport.js authentication strategies
│   ├── /redis.js               # Redis client
│   ├── /server.js              # Node.js server (entry point)
│   └── /types.js               # Flow type definitions
├── /tools/                     # Build automation scripts and utilities
├── docker-compose.yml          # Defines Docker services, networks and volumes
├── docker-compose.override.yml # Overrides per developer environment (not under source control)
├── Dockerfile                  # Commands for building a Docker image for production
├── package.json                # List of project dependencies
└── postgres-initdb.sh          # Configuration script for the PostgreSQL Docker container

Prerequisites

Getting Started

Just clone the repo and run docker-compose up:

git clone https://github.com/kriasoft/nodejs-api-starter.git example-api
cd example-api                  # Change current directory to the newly created one
docker-compose up               # Launch Docker containers with the Node.js API app running inside

The API server must become available at http://localhost:8080/graphql (live demo).

Once the Docker container named api is started, the Docker engine executes node tools/run.js command that installs Node.js dependencies, migrates database schema to the latest version, compiles Node.js app from source files (see src) and launches it with "live reload" on port 8080.

If you need to manually rollback and re-apply the latest database migration file, run the following:

yarn docker-db-rollback         # Rollbacks the latest migration
yarn docker-db-migrate          # Migrates database to the latest version (see /migrates folder)
yarn docker-db-seed             # Seeds database with test data (see /seeds folder)

In order to open a shell from inside the running "api" container, run:

docker-compose exec api /bin/sh

Similarly, if you need to open a PostgreSQL shell (psql), execute this command:

docker-compose exec db psql <db> -U postgres

For the full list of automation scripts available in this project, please reffer to "scripts" section in the package.json file and the tools folder.

Testing

yarn lint                       # Find problematic patterns in code
yarn check                      # Check source code for type errors
yarn docker-test                # Run unit tests once inside a Docker container
yarn docker-test-watch          # Run unit tests in watch mode inside a Docker container

For more information visit http://facebook.github.io/jest/

Debugging

In order to run the app with V8 inspector enabled, simply replace node tools/run.js with node --inspect=0.0.0.0:9229 tools/run.js in either docker-compose.yml file or, even better, in docker-compose.override.yml. Then restart the app (docker-compose up) and attach your debugger to 127.0.0.1:9230 (see .vscode/launch.json)

Keeping Up-to-Date

If you keep the original Git history after cloning this repo, you can always fetch and merge the recent updates back into your project by running:

git remote add nodejs-api-starter https://github.com/kriasoft/nodejs-api-starter.git
git checkout master
git fetch nodejs-api-starter
git merge nodejs-api-starter/master
docker-compose build --no-cache
docker-compose run --rm --no-deps api yarn
docker-compose up

NOTE: Try to merge as soon as the new changes land on the master branch in Node.js API Starter repository, otherwise your project may differ too much from the base/upstream repo.

Deployment

Customize the deployment script found in tools/publish.js if needed. Then whenever you need to deploy your app to a remote server simply run:

node tools/publish <host>       # where <host> is the name of your web server (see ~/.ssh/config)

Not sure where to deploy your app? DigitalOcean is a great choice in many cases (get $10 credit)

Contributing

Anyone and everyone is welcome to contribute. Start by checking out the list of open issues marked help wanted. However, if you decide to get involved, please take a moment to review the guidelines.

Reference Articles and Tutorials

Related Projects

  • GraphQL.js — The JavaScript reference implementation for GraphQL
  • DataLoader — Batching and caching for GraphQL data access layer
  • React Starter Kit — Isomorphic web app boilerplate (React, Node.js, Babel, Webpack, CSS Modules)
  • React Static Boilerplate — Single-page application (SPA) starter kit (React, Redux, Webpack, Firebase)
  • Membership Database — SQL schema boilerplate for user accounts, profiles, roles, and auth claims

License

Copyright © 2016-present Kriasoft. This source code is licensed under the MIT license found in the LICENSE.txt file.


Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors