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).
https://graphql-demo.kriasoft.com
- 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
.
├── /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- 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.
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=localThe API server must become available at http://localhost:8080/graphql (live demo).
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-testUpon 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 versionHINT: 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)$ 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
$ 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 environmentFor more information refer to the Deployment guide in the project's Wiki.
Use yarn start-debug instead of yarn start then attach VS Code debugger to the running
instance of the app.
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 installNOTE: 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.
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.
- 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
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