typescript-advanced

🚀 Advanced starter code for a scalable, production-ready GraphQL server written in TypeScript, including authentication and realtime functionality with GraphQL subscriptions.

Features

• Scalable GraphQL Server: graphql-yoga based on Apollo Server & Express
• GraphQL-native database: Includes GraphQL database binding to Graphcool (running on MySQL)
• Out-of-the-box support for GraphQL Playground & Tracing
• Simple data model – easy to adjust
• Preconfigured graphql-config setup
• Authentication based on email & password
• Realtime functionality with GraphQL subscriptions (coming soon)

Requirements

You need to have the following things installed:

• Node 8+ & TypeScript
• GraphQL CLI: npm i -g graphql-cli
• GraphQL Playground desktop app (optional): Download

Getting started

# Bootstrap GraphQL server in directory `my-app`, based on `typescript-advanced` boilerplate
graphql create my-app --boilerplate typescript-advanced

# choose the Graphcool cluster you want to deploy to

# Navigate to the new project
cd my-app

# Start server (runs on http://localhost:4000)
yarn start

# Open Playground to explore GraphQL API
yarn playground

Docs

Commands

• yarn start starts GraphQL server
• yarn debug starts GraphQL server in debug mode (open chrome://inspect/#devices to debug)
• yarn playground opens the GraphQL Playground
• yarn graphcool access to local version of graphcool CLI

Project structure

/ - configuration files

• .env Contains important environment variables for development. Read about how it works here.
• .graphqlconfig.yml GraphQL configuration file containing the endpoints and schema configuration. Used by the graphql-cli and the GraphQL Playground. See graphql-config for more information.

/database - datamodel

• database/graphcool.yml The configuration file for your database service (documentation).
• database/datamodel.graphql contains the data model that you define for your database service (written in SDL).

/src - application server

• src/schema.graphql defines your application schema. It contains the GraphQL API that you want to expose to your client applications.
• src/index.ts is the entry point of your server, putting everything together and starting the GraphQLServer from graphql-yoga.
• src/resolvers/ contains the actual business logic of your application. In GraphQL, you implement resolver functions that resolve a specific query being requested.

/src/generated - generated files

• src/generated/graphcool.graphql defines the database schema. It contains the GraphQL API exposed by the Graphcool Database. This file is automatically generated every time graphcool deploy is executed, according to the datamodel in database/datamodel.graphql.
• src/generated/graphcool.ts static TypeScript type definitions for graphcool-binding, enabling autocompletion in your IDE. This file is automatically generated using graphql prepare every time graphcool deploy is executed.

Common questions

I'm getting a 'Schema could not be fetched.' error after deploying, what gives?

Access to the Graphcool API is secured by a secret. This also applies to the introspection query. Using the latest version of GraphQL Playground, the Authorization header should automatically be setup with a proper JWT signing the secret. If that's not the case, you can follow these steps to access your API:

1. Visit http://jwtbuilder.jamiekurtz.com/
2. Replace the Key at the bottom of the page with your secret from the .env file
3. Click Create signed JWT and copy the obtained token
4. Now, to access the schema, use the Authorization: Bearer <token> header, or in the GraphQL Playground set it as JSON:

   {
     "Authorization": "Bearer <token>"
   }

5. Reload the schema in the Playground (the refresh-button is located right next to the URL of the server)

Note: Currently, no content of the signed JWT is verified by the database! This will be implemented according to this proposal at a later stage.

Contributing

Your feedback is very helpful, please share your opinion and thoughts! If you have any questions, join the #graphql-boilerplate channel on our Slack.