{"id":13990883,"url":"https://github.com/w3tecch/express-graphql-typescript-boilerplate","last_synced_at":"2025-10-03T01:30:47.090Z","repository":{"id":57998232,"uuid":"78244268","full_name":"w3tecch/express-graphql-typescript-boilerplate","owner":"w3tecch","description":"A starter kit for building amazing GraphQL API's with TypeScript and express by @w3tecch","archived":true,"fork":false,"pushed_at":"2018-11-11T13:29:22.000Z","size":234,"stargazers_count":185,"open_issues_count":5,"forks_count":72,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-09-28T06:41:53.140Z","etag":null,"topics":["api","backend","boilerplate","expressjs","graphql","gulp","jasmine","knex","nodejs","starter-kit","tslint","typescript","wallaby"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/w3tecch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-06T22:40:06.000Z","updated_at":"2024-07-11T11:15:51.000Z","dependencies_parsed_at":"2022-09-01T02:31:09.295Z","dependency_job_id":null,"html_url":"https://github.com/w3tecch/express-graphql-typescript-boilerplate","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Fexpress-graphql-typescript-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Fexpress-graphql-typescript-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Fexpress-graphql-typescript-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3tecch%2Fexpress-graphql-typescript-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w3tecch","download_url":"https://codeload.github.com/w3tecch/express-graphql-typescript-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235059234,"owners_count":18929279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backend","boilerplate","expressjs","graphql","gulp","jasmine","knex","nodejs","starter-kit","tslint","typescript","wallaby"],"created_at":"2024-08-09T13:03:27.296Z","updated_at":"2025-10-03T01:30:41.797Z","avatar_url":"https://github.com/w3tecch.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# express-graphql-typescript-boilerplate\n\n[![Build Status](https://travis-ci.org/w3tecch/express-graphql-typescript-boilerplate.svg?branch=master)](https://travis-ci.org/w3tecch/express-graphql-typescript-boilerplate.svg?branch=master)\n\nA [GraphQL](http://graphql.org/) starter kit for building amazing API's in [TypeScript](https://www.typescriptlang.org/) and with [Express.js](http://expressjs.com/) framework.\n\nThis 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\n* VSCode tasks and launch configuration\n* Improved GraphQL Error Handling, so that the error stack will be shown in the console\n* Multiple environemnt configurations\n* Basic security configuration\n* Basic cors configuration\n* Basic logger configuration\n* Advanced GraphQL-Context logic, so we can use repos, dataloader and other stuff in each resolver\n* Complete [Knex.js](http://knexjs.org/) integration with seeders and migration\n* [DataLoaders](https://github.com/facebook/dataloader)\n* Extended GraphQL-Query and GraphQL-Field with a lite [Hook-System](###Hook-System)\n* A lot of examples like:\n    * Pagination\n    * Search query with filter\n    * Custom GraphQL-Types like a date type\n    * Migtation and seeders\n    * Models\n    * Testing examples\n    * and many more, just have a look\n\n## Getting Started\n### Prerequisites\nInstall [Node.js](http://nodejs.org)\n* on OSX use [homebrew](http://brew.sh) `brew install node`\n* on Windows use [chocolatey](https://chocolatey.org/) `choco install nodejs`\n\n## Installing\n* `fork` this repo\n* `clone` your fork\n* `npm install` to install all dependencies\n* `npm run install:typings` to install all typings\n* Create new database. You will find the name in the `src/config.ts` file.\n* `npm run db:migrate` to create the schema\n* `npm run db:seed` to insert some test data\n* `npm run serve` to start the dev server in another tab\n\n## Running the app\nAfter you have installed all dependencies you can now run the app.\nRun `npm run serve` to start a local server using `nodemon` which will watch for changes and then will restart the sever.\nThe 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/`).\n\n## Scripts / Commands\n### Install\n* Install all dependencies with `npm install`\n* Install all typings with `npm run install:typings`\n* To install all dependencies and typings use `npm run install:dev`\n* Remove not needed libraries with `npm run install:clean`\n\n### Linting\n* Run code analysis using `npm run lint`. This runs tshint.\n* There is also a vscode task for this called lint.\n\n### Tests\n* Run the unit tests using `npm test` or `npm run test:pretty` for more detailed reporting.\n* There is also a vscode task for this called test.\n\n### Running in dev mode\n* Run `npm run serve` to start nodemon with ts-node, which will serve your app.\n* The server address will be displayed to you as `http://0.0.0.0:3000`\n\n### Cleaning the project\n* Run `npm run clean` to remove all generated JavaScript files.\n\n### Building the project and run it\n* Run `npm run build` to generated all JavaScript files from your TypeScript sources. After this step you can deploy the app on any server.\n* There is also a vscode task for this called build.\n* To start the builded app use `npm start`.\n* With `npm run zip` it will generate the JavaScript source and pack them into to a deployable zip file into the dist folder.\n\n### Docs\n* Run `npm run docs` to generate all doc files and serve it on `http://0.0.0.0:8080`\n\n### Seed\n* Run `npm run db:seed` to seed some data into the database\n\n### Migration\n* Run `npm run db:migrate` to migration the new schema to the database\n* Run `npm run db:migrate:rollback` to rollback one version\n\n## Exploring the boilerplate\n### Structure\n```\nexpress-graphql-typescript-boilerplate\n |-- .vscode/                                   * our vscode tasks, launch configuration and some settings\n |-- build/                                     * our task runner configurations and tasks\n |    |-- tasks/                                * gulp tasks\n |    |-- paths.js                              * project path setup for our gulp tasks\n |    |-- util.js                               * our gulp helper functions\n |\n |-- docs/                                      * our generated doc files\n |\n |-- src/                                       * our source files that will be compiled to javascript\n |    |\n |    |-- context/                              * graphql context\n |    |    |-- Context.ts                       * our graphql context class\n |    |    |-- DataloadersContext.ts            * our collection of all dataloaders\n |    |    |-- ServicesContext.ts               * our collection of all repositories\n |    |\n |    |-- core/                                 * our core functionalities\n |    |    |-- Bootstrap.ts                     * our express helper functions to init and run the server\n |    |    |-- Database.ts                      * our database setup\n |    |    |-- Environment.ts                   * gets us the configuration for the given environment\n |    |    |-- GraphQLErrorHandling.ts          * our error handling\n |    |    |-- Logger.ts                        * our logger configurations\n |    |    |-- Server.ts                        * our server error handling\n |    |    |-- Tables.ts                        * our database table names\n |    |    |-- Utils.ts                         * our collection of util functions\n |    |\n |    |-- database/                             * our database tasks\n |    |    |-- factories                        * our factories to create simple fake data\n |    |    |-- migrations                       * our database migration tasks\n |    |    |-- seeds                            * our database seeder tasks\n |    |\n |    |-- exceptions/                           * our errors to throw to the user\n |    |    |-- Exception.ts                     * our basic user error all other errors should inherit from this one\n |    |    |-- NotFoundException.ts             * a basic not found error\n |    |\n |    |-- middlewares/                          * our express custom middlewares (/*.middleware.ts)\n |    |\n |    |-- models/                               * our database models (/*.model.ts)\n |    |\n |    |-- repositories/                         * use a repository to fetch the date of the database\n |    |    |-- **/*Repository.ts\n |    |\n |    |-- 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\n |    |    |-- **/*Services.ts\n |    |\n |    |-- routes/                               * defines our application routes\n |    |    |-- **/*Routes.ts\n |    |\n |    |-- schemas/                              * our graphql schema definitions (use a single file for every graphql object action)\n |    |    |-- arguments/                       * our graphql argument files\n |    |    |-- fields/                          * our graphql field files\n |    |    |-- mutations/                       * our graphql mutation files\n |    |    |-- queries/                         * our graphql query files\n |    |    |-- types/                           * our graphql type files\n |    |\n |    |-- index.ts                              * main entry point for our application\n |    |-- RootValue.ts                          * RootValue with some functions for all the queries and mutations\n |    |-- config.ts                             * has our configuration for our different environments\n |\n |-- test/                                      * our test files that will test our application\n |    |-- mocks                                 * we use this to simulate other functions, classes or objects\n |    |-- unit/**/*.spec.ts                     * our unit test cases\n |\n |-- typings_custom/                            * our local type definitions\n |\n |-- knexfile.ts                                * this has our database configuration from the config.ts\n |-- gulpfile.js                                * entry point for our gulp tasks\n |-- nodemon.json                               * nodemon setup, so that it uses typescript and runs tslint\n |-- package.json                               * what npm uses to manage it's dependencies\n |-- tslint.json                                * typescript lint config\n |-- typedoc.json                               * typescript documentation generator\n |-- tsconfig.json                              * typescript config\n |-- wallaby.js                                 * our wallaby configuration\n```\n\n### Hook-System\n```typescript\n// We extend the AbstractQuery with the hook system. This\n// gives us the 3 new methods called before, run and after.\nexport class FindAllBooksQuery extends AbstractQuery implements GraphQLFieldConfig {\n\n    public type = new GraphQLList(BookType);\n    public allow = ['admin'];\n    public args = {\n        limit: new LimitArgument(),\n        offset: new OffsetArgument()\n    };\n\n    // This will be called after the allow checking\n    public before(context: Context, args: common.PageinationArguments): Promise\u003ccommon.PageinationArguments\u003e {\n        log.debug('hook before args', args);\n        LimitArgument.validate(args.limit);\n        OffsetArgument.validate(args.limit);\n        return Promise.resolve(args);\n    }\n\n    // As long as the before function was okay this will be called afterwards\n    public execute(root: RootValue, args: common.PageinationArguments, context: Context): Promise\u003cmodels.book.Attributes\u003e {\n        log.debug('resolve findAllBooks()');\n        return context.Repositories.BookRepository.findAllBooks({\n            limit: args.limit,\n            offset: args.offset\n        });\n    }\n\n    // And at least before the results go back to our client it will pass this after function\n    public after(result: models.book.Attributes, context: Context, args: common.PageinationArguments): Promise\u003cmodels.book.Attributes\u003e {\n        log.debug('hook after args', args);\n        return Promise.resolve(result);\n    }\n}\n```\n\n## Related Projects\n* [GraphQL.js](http://graphql.org/) — The JavaScript reference implementation for GraphQL\n* [DataLoader](https://github.com/facebook/dataloader) — Batching and caching for GraphQL data access layer\n* [aurelia-typescript-boilerplate](https://github.com/w3tecch/aurelia-typescript-boilerplate) - An Aurelia starter kit with TypeScript\n* [express-typescript-boilerplate](https://github.com/w3tecch/express-typescript-boilerplate) - Boilerplate for an restful express-apllication written in TypeScript\n\n## License\n [MIT](/LICENSE)\n\n---\nMade with ♥ by Gery Hirschfeld ([@GeryHirschfeld1](https://twitter.com/GeryHirschfeld1)) and [contributors](https://github.com/w3tecch/express-graphql-typescript-boilerplate/graphs/contributors)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3tecch%2Fexpress-graphql-typescript-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw3tecch%2Fexpress-graphql-typescript-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3tecch%2Fexpress-graphql-typescript-boilerplate/lists"}