Boilerplate and tooling for authoring (serverless) 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 Firesbase Starter etc).
This project was bootstrapped with Node.js API Starter Kit
(support).
Tech Stack
- Node.js, Yarn, TypeScript, Babel, Prettier — core platform and dev tools
- GraphQL.js, GraphQL.js Relay, DataLoader, validator — GraphQL schema and API endpoint
- PostgreSQL, Knex, pg — data access and db automation (migrations, seeds)
- Jest - unit and snapshot testing
Directory Layout
.
├── /build/ # The compiled output (via Babel)
├── /migrations/ # Database schema migrations
├── /scripts/ # Build automation scripts and utilities
├── /seeds/ # Scripts with reference/sample data
├── /src/ # Node.js application source files
│ ├── /mutations/ # GraphQL API mutations
│ ├── /queries/ # GraphQL API query fields
│ ├── /types/ # GraphQL custom types
│ ├── /utils/ # Utility functions (mapTo, mapToMany etc.)
│ ├── /auth.js # Authentication middleware
│ ├── /context.ts # Data loaders and other context-specific stuff
│ ├── /db.ts # Database access and connection pooling (via Knex)
│ ├── /errors.ts # Custom errors and error reporting
│ ├── /fields.ts # Helper functions for creating GraphQL query fields
│ ├── /index.ts # Node.js application entry point
│ ├── /node.ts # GraphQL Node interface
│ ├── /schema.ts # GraphQL schema type
│ └── /validator.ts # Input validation helpers
├── babel.config.js # Babel configuration
├── docker-stack.yml # Allows to launch PostgreSQL via Docker
├── package.json # List of project dependencies
├── schema.graphql # GraphQL schema file (auto-generated)
└── tsconfig.json # TypeScript configuration
Prerequisites
- Node.js v10 or higher + Yarn package manager
- PostgreSQL (can be local or remote instance, e.g. Google Cloud SQL)
- Optionally VS Code editor with Project Snippets,
EditorConfig, ESLint, and Prettier
plug-ins.
Getting Started
Just clone the repo, tweak .env file in the root of the project, and run yarn start:
$ git clone https://github.com/kriasoft/nodejs-api-starter.git example-api
$ cd example-api # Change current directory to the newly created one
$ yarn install # Install Node.js dependencies
$ yarn start # Launch Node.js API application. Or, yarn start --env=local
The API server must become available at http://localhost:8080/graphql
(live demo).
How to Migrate Database Schema
While the app is in development, you can use a simplified migration workflow by
creating a backup of your existing database, making changes to the existing
migration file (see migrations/20180101000000_initial.ts), re-apply the
migration and restore data from the backup file (backup.sql):
$ yarn db-backup --env=dev # Or, yarn db-backup --env=test
$ yarn db-reset-dev # Or, yarn db-reset-test
Upon deployment to production, switch to normal migration workflow:
$ yarn db-change <name> # Create a new database migration file
$ yarn db-migrate --env=dev # Migrate database to the latest version
HINT: Test your migration thoroughly with a local instance of the DB first
(by using --env=local or --env=dev (default) flag) then apply it to your
test or prod database instance using --env=test or --env=prod command
argument.
Other helpful database scripts:
$ yarn db-version --env=dev # Print the version number of the last migration
$ yarn db-rollback --env=dev # Rollback the latest migration
$ yarn db-restore --env=dev # Restore database from backup.sql
$ yarn db-seed --env=dev # Seed database with test data
$ yarn db --env=dev # Open Knex.js REPL shell (type ".exit" for exit)
$ yarn psql --env=dev # Open PostgreSQL shell (type "\q" for exit)
How to Test
$ yarn lint # Check JavaScript and CSS code for potential issues
$ yarn lint-fix # Attempt to automatically fix ESLint warnings
$ yarn check # Check source code for type errors
$ yarn test # Run unit tests. Or, `yarn test --watch`
For more information visit https://jestjs.io/docs/getting-started
How to Deploy
$ yarn build # Build the app in production mode (NODE_ENV=production)
$ yarn deploy-test # Deploy the app to TEST environment
$ yarn deploy-prod # Deploy the app to PROD environment
For more information refer to the Deployment
guide in the project's Wiki.
How to Debug
Use yarn start-debug instead of yarn start then attach VS Code debugger to the running
instance of the app.
How to Update
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 upstream https://github.com/kriasoft/nodejs-api-starter.git
$ git checkout master
$ git fetch upstream
$ git merge upstream/master
$ yarn install
NOTE: Try to merge as soon as the new changes land on the master branch in the upstream
repository, otherwise your project may differ too much from the base/upstream repo.
Alternatively, you can use a folder diff tool like Beyond Compare for keeping your project
up to date with the base repository.
How to Contribute
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.
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 file.
Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors
