express-graphql-typescript-boilerplate

A GraphQL starter kit for building amazing API's in TypeScript and with Express.js framework.

This seed repository has a complete GraphQL starter kit written in TypeSciprt. For building our API we use various gulp-tasks. We use jasmine and Wallaby for our unit-testing. And there are a lot more awesome features like

VSCode tasks and launch configuration
Improved GraphQL Error Handling, so that the error stack will be shown in the console
Multiple environemnt configurations
Basic securty configuration
Basic cors configuration
Basic logger configuration
Advanced GraphQL-Context logic, so we can use repos, dataloader and other stuff in each resolver
Complete Knex.js integration with seeders and migration
DataLoaders
Extended GraphQL-Query and GraphQL-Field with a lite Hook-System
A lot of examples like:
- Pagination
- Search query with filter
- Custom GraphQL-Types like a date type
- Migtation and seeders
- Models
- Testing examples
- and many more, just have a look

Getting Started

Prerequisites

Install Node.js

on OSX use homebrew brew install node
on Windows use chocolatey choco install nodejs

Installing

fork this repo
clone your fork
npm install to install all dependencies
npm run install:typings to install all typings
Create new database. You will find the name in the src/config.ts file.
npm run db:migrate to create the schema
npm run db:seed to insert some test data
npm run serve to start the dev server in another tab

Running the app

After you have installed all dependencies you can now run the app. Run npm run serve to start a local server using nodemon which will watch for changes and then will restart the sever. The port will be displayed to you as http://0.0.0.0:3000 (or if you prefer IPv6, if you're using express server, then it's http://[::1]:3000/).

Scripts / Commands

Install

Install all dependencies with npm install
Install all typings with npm run install:typings
To install all dependencies and typings use npm run install:dev
Remove not needed libraries with npm run install:clean

Linting

Run code analysis using npm run lint. This runs tshint.
There is also a vscode task for this called lint.

Tests

Run the unit tests using npm test or npm run test:pretty for more detailed reporting.
There is also a vscode task for this called test.

Running in dev mode

Run npm run serve to start nodemon with ts-node, which will serve your app.
The server address will be displayed to you as http://0.0.0.0:3000

Cleaning the project

Run npm run clean to remove all generated JavaScript files.

Building the project and run it

Run npm run build to generated all JavaScript files from your TypeScript sources. After this step you can deploy the app on any server.
There is also a vscode task for this called build.
To start the builded app use npm start.
With npm run zip it will generate the JavaScript source and pack them into to a deployable zip file into the dist folder.

Docs

Run npm run docs to generate all doc files and serve it on http://0.0.0.0:8080

Seed

Run npm run db:seed to seed some data into the database

Migration

Run npm run db:migrate to migration the new schema to the database
Run npm run db:migrate:rollback to rollback one version

Exploring the boilerplate

Structure

express-graphql-typescript-boilerplate
 |-- .vscode/                                   * our vscode tasks, launch configuration and some settings
 |-- build/                                     * our task runner configurations and tasks
 |    |-- tasks/                                * gulp tasks
 |    |-- paths.js                              * project path setup for our gulp tasks
 |    |-- util.js                               * our gulp helper functions
 |
 |-- docs/                                      * our generated doc files
 |
 |-- src/                                       * our source files that will be compiled to javascript
 |    |
 |    |-- context/                              * graphql context
 |    |    |-- Context.ts                       * our graphql context class
 |    |    |-- DataloadersContext.ts            * our collection of all dataloaders
 |    |    |-- ServicesContext.ts               * our collection of all repositories
 |    |
 |    |-- core/                                 * our core functionalities
 |    |    |-- Bootstrap.ts                     * our express helper functions to init and run the server
 |    |    |-- Database.ts                      * our database setup
 |    |    |-- Environment.ts                   * gets us the configuration for the given environment
 |    |    |-- GraphQLErrorHandling.ts          * our error handling
 |    |    |-- Logger.ts                        * our logger configurations
 |    |    |-- Server.ts                        * our server error handling
 |    |    |-- Tables.ts                        * our database table names
 |    |    |-- Utils.ts                         * our collection of util functions
 |    |
 |    |-- database/                             * our database tasks
 |    |    |-- factories                        * our factories to create simple fake data
 |    |    |-- migrations                       * our database migration tasks
 |    |    |-- seeds                            * our database seeder tasks
 |    |
 |    |-- exceptions/                           * our errors to throw to the user
 |    |    |-- Exception.ts                     * our basic user error all other errors should inherit from this one
 |    |    |-- NotFoundException.ts             * a basic not found error
 |    |
 |    |-- middlewares/                          * our express custom middlewares (/*.middleware.ts)
 |    |
 |    |-- models/                               * our database models (/*.model.ts)
 |    |
 |    |-- repositories/                         * use a repository to fetch the date of the database
 |    |    |-- **/*Repository.ts
 |    |
 |    |-- services/                             * use a services to separate the logic that retrieves the data and maps it to the entity model from the business logic that acts on the model
 |    |    |-- **/*Services.ts
 |    |
 |    |-- routes/                               * defines our application routes
 |    |    |-- **/*Routes.ts
 |    |
 |    |-- schemas/                              * our graphql schema definitions (use a single file for every graphql object action)
 |    |    |-- arguments/                       * our graphql argument files
 |    |    |-- fields/                          * our graphql field files
 |    |    |-- mutations/                       * our graphql mutation files
 |    |    |-- queries/                         * our graphql query files
 |    |    |-- types/                           * our graphql type files
 |    |
 |    |-- index.ts                              * main entry point for our application
 |    |-- RootValue.ts                          * RootValue with some functions for all the queries and mutations
 |    |-- config.ts                             * has our configuration for our different environments
 |
 |-- test/                                      * our test files that will test our application
 |    |-- mocks                                 * we use this to simulate other functions, classes or objects
 |    |-- unit/**/*.spec.ts                     * our unit test cases
 |
 |-- typings_custom/                            * our local type definitions
 |
 |-- knexfile.ts                                * this has our database configuration from the config.ts
 |-- gulpfile.js                                * entry point for our gulp tasks
 |-- nodemon.json                               * nodemon setup, so that it uses typescript and runs tslint
 |-- package.json                               * what npm uses to manage it's dependencies
 |-- tslint.json                                * typescript lint config
 |-- typedoc.json                               * typescript documentation generator
 |-- tsconfig.json                              * typescript config
 |-- wallaby.js                                 * our wallaby configuration

Hook-System

// We extend the AbstractQuery with the hook system. This
// gives us the 3 new methods called before, run and after.
export class FindAllBooksQuery extends AbstractQuery implements GraphQLFieldConfig {

    public type = new GraphQLList(BookType);
    public allow = ['admin'];
    public args = {
        limit: new LimitArgument(),
        offset: new OffsetArgument()
    };

    // This will be called after the allow checking
    public before(context: Context, args: common.PageinationArguments): Promise<common.PageinationArguments> {
        log.debug('hook before args', args);
        LimitArgument.validate(args.limit);
        OffsetArgument.validate(args.limit);
        return Promise.resolve(args);
    }

    // As long as the before function was okay this will be called afterwards
    public execute(root: RootValue, args: common.PageinationArguments, context: Context): Promise<models.book.Attributes> {
        log.debug('resolve findAllBooks()');
        return context.Repositories.BookRepository.findAllBooks({
            limit: args.limit,
            offset: args.offset
        });
    }

    // And at least before the results go back to our client it will pass this after function
    public after(result: models.book.Attributes, context: Context, args: common.PageinationArguments): Promise<models.book.Attributes> {
        log.debug('hook after args', args);
        return Promise.resolve(result);
    }
}

Related Projects

GraphQL.js — The JavaScript reference implementation for GraphQL
DataLoader — Batching and caching for GraphQL data access layer
aurelia-typescript-boilerplate - An Aurelia starter kit with TypeScript
express-typescript-boilerplate - Boilerplate for an restful express-apllication written in TypeScript

License

MIT

Made with ♥ by Gery Hirschfeld (@GeryHirschfeld1) and contributors

FerrielMelarpis/express-graphql-typescript-boilerplate