Node.js API Starter Kit
Node.js API Starter Kit is a boilerplate and tooling for authoring data API backends with Node.js, JavaScript (via Babel) and GraphQL. It's meant to be paired with a web and/or mobile application project such as React Starter Kit.
This project is maintained with support from
Features
✓ Cross-platform development on macOS, Windows or Linux inside Docker, single dev dependency
✓ GraphQL boilerplate, everything needed to get started building a GraphQL API endpoint / gateway
✓ PostgreSQL database schema boilerplate and migration tools (see tools
, migrations
)
✓ Authentication and authorization via Passport.js (see src/passport.js
, src/routes/account.js
)
✓ Session and cache management with Redis and DataLoader (see stop using JWT for sessions)
✓ 24/7 community support on Gitter + premium support on Skype (book a session)
Directory Layout
.
├── /build/ # The compiled output (via Babel)
├── /config/ # Configuration files (for Docker containers etc.)
├── /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
│ ├── /models/ # Data access models, e.g. User.create({ email })
│ ├── /routes/ # Express routes, e.g. /login/facebook
│ ├── /types/ # GraphQL types with resolve functions
│ │ ├── /Node.js # Relay's "node" definitions
│ │ ├── /UserType.js # User account (id, email, etc.)
│ │ ├── /ViewerType.js # The top-level GraphQL object type
│ │ └── /... # etc.
│ ├── /app.js # Express.js application
│ ├── /db.js # Database access and connection pooling (via Knex)
│ ├── /passport.js # Passport.js authentication strategies
│ ├── /redis.js # Redis client
│ ├── /schema.js # GraphQL schema
│ └── /server.js # Node.js server (entry point)
├── /test/ # Unit, integration and load tests
├── /tools/ # Build automation scripts and utilities
├── docker-compose.yml # Defines Docker services, networks and volumes
├── Dockerfile # Commands for building a Docker image for production
├── package.json # The list of project dependencies
└── yarn.lock # Fixed versions of all the dependencies
Getting Started
Make sure that you have Docker v17 or newer installed plus a good text editor or IDE (VS Code, WebStorm or another), clone the repo and launch the app with Docker Compose:
git clone -o nodejs-api-starter -b master --single-branch \
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
.
In order to open a new terminal session from inside the api
Docker container run:
docker-compose exec api /bin/sh
From this shell you can run automation scripts such as yarn test
, yarn run db:migrate
etc.
Find the full list of scripts available inside the tools
folder and
the package.json
file.
Testing
yarn run lint # Find problematic patterns in code
yarn run check # Check source code for type errors
yarn run test # Run unit tests once
yarn run test:watch # Run unit tests in watch mode
Debugging
In order to run the app with V8 inspector enabled, simply set NODE_DEBUG=true
flag in
the docker-compose.yml
file, restart the app (docker-compose up
) and
attach your debugger to 127.0.0.1:9229
(see .vscode/launch.json
for VS Code as an example).
Keeping Up-to-Date
If you keep the original Git history after clonning this repo, you can always fetch and merge the recent updates back into your project by running:
git checkout master
git fetch nodejs-api-starter
git merge nodejs-api-starter/master
docker-compose up
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.
Books 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
Support
- #nodejs-api-starter on Stack Overflow — Questions and answers
- #nodejs-api-starter on Gitter — Watch announcements, share ideas and feedback
- GitHub Issues — Check open issues, send feature requests
- @koistya on Codementor, HackHands or Skype — Private consulting and customization requests
License
Copyright © 2016-present Kriasoft, LLC. This source code is licensed under the MIT license found in the LICENSE.txt file. The documentation to the project is licensed under the CC BY-SA 4.0 license.
Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors