Name: graphql-yoga
Owner: Prisma
Description: ? Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience
Created: 2017-11-15 10:35:08.0
Updated: 2018-05-24 15:23:44.0
Pushed: 2018-05-24 02:23:32.0
Size: 960
Language: TypeScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience
graphql-yoga
is based on the following libraries & tools:
express
/apollo-server
: Performant, extensible web server frameworkgraphql-subscriptions
/subscriptions-transport-ws
: GraphQL subscriptions servergraphql.js
/graphql-tools
: GraphQL engine & schema helpersgraphql-playground
: Interactive GraphQL IDEapplication/json
and application/graphql
content-typenow
, up
, AWS Lambda, Heroku etc add graphql-yoga
rt { GraphQLServer } from 'graphql-yoga'
.. or using `require()`
onst { GraphQLServer } = require('graphql-yoga')
t typeDefs = `
pe Query {
hello(name: String): String!
t resolvers = {
ery: {
hello: (_, { name }) => `Hello ${name || 'World'}`,
t server = new GraphQLServer({ typeDefs, resolvers })
er.start(() => console.log('Server is running on localhost:4000'))
To get started with
graphql-yoga
, follow the instructions in the READMEs of the examples.
GraphQLServer
constructor(props: Props): GraphQLServer
The props
argument accepts the following fields:
| Key | Type | Default | Note |
| — | — | — | — |
| typeDefs
| String | null
| Contains GraphQL type definitions in SDL or file path to type definitions (required if schema
is not provided *) |
| resolvers
| Object | null
| Contains resolvers for the fields specified in typeDefs
(required if schema
is not provided *) |
| schema
| Object | null
| An instance of GraphQLSchema
(required if typeDefs
and resolvers
are not provided *) |
| context
| Object or Function | {}
| Contains custom data being passed through your resolver chain. This can be passed in as an object, or as a Function with the signature (req: ContextParameters) => any
** |
(*) There are two major ways of providing the schema information to the
constructor
:
- Provide
typeDefs
andresolvers
and omit theschema
, in this casegraphql-yoga
will construct theGraphQLSchema
instance usingmakeExecutableSchema
fromgraphql-tools
.- Provide the
schema
directly and omittypeDefs
andresolvers
.(**) Notice that the
req
argument is an object of the shape{ request, connection }
which either carries arequest: Request
property (in case it's aQuery
/Mutation
resolver) or aconnection: SubscriptionOptions
property (in case it's aSubscription
resolver).Request
is imported from Express.js.SubscriptionOptions
is from thegraphql-subscriptions
package.SubscriptionOptions
are getting the connectionParams automatically injected underSubscriptionOptions.context.[CONNECTION_PARAMETER_NAME]
Here is example of creating a new server:
t typeDefs = `
pe Query {
hello(name: String): String!
t resolvers = {
ery: {
hello: (_, { name }) => `Hello ${name || 'World'}`,
t server = new GraphQLServer({ typeDefs, resolvers })
start(options: Options, callback: ((options: Options) => void) = (() => null)): Promise<void>
Once your GraphQLServer
is instantiated, you can call the start
method on it. It takes two arguments: options
, the options object defined above, and callback
, a function that's invoked right before the server is started. As an example, the callback
can be used to print information that the server was now started.
The options
object has the following fields:
| Key | Type | Default | Note |
| — | — | — | — |
| cors
| Object | null
| Contains configuration options for cors |
| tracing
| Boolean or String | 'http-header'
| Indicates whether Apollo Tracing should be en- or disabled for your server (if a string is provided, accepted values are: 'enabled'
, 'disabled'
, 'http-header'
) |
| port
| Number | 4000
| Determines the port your server will be listening on (note that you can also specify the port by setting the PORT
environment variable) |
| endpoint
| String | '/'
| Defines the HTTP endpoint of your server |
| subscriptions
| String or false
| '/'
| Defines the subscriptions (websocket) endpoint for your server; setting to false
disables subscriptions completely |
| playground
| String or false
| '/'
| Defines the endpoint where you can invoke the Playground; setting to false
disables the playground endpoint |
| uploads
| Object or false
| null
| Provides information about upload limits; the object can have any combination of the following three keys: maxFieldSize
, maxFileSize
, maxFiles
; each of these have values of type Number; setting to false
disables file uploading |
Additionally, the options
object exposes these apollo-server
options:
| Key | Type | Note |
| — | — | — |
| cacheControl
| Boolean | Enable extension that returns Cache Control data in the response |
| formatError
| Number | A function to apply to every error before sending the response to clients |
| logFunction
| LogFunction | A function called for logging events such as execution times |
| rootValue
| any | RootValue passed to GraphQL execution |
| validationRules
| Array of functions | DAdditional GraphQL validation rules to be applied to client-specified queries |
| fieldResolver
| GraphQLFieldResolver | Provides information about upload limits; the object can have any combination of the following three keys: maxFieldSize
, maxFileSize
, maxFiles
; each of these have values of type Number; setting to false
disables file uploading |
| formatParams
| Function | A function applied for each query in a batch to format parameters before execution |
| formatResponse
| Function | A function applied to each response after execution |
| debug
| boolean | Print additional debug logging if execution errors occur |
t options = {
rt: 8000,
dpoint: '/graphql',
bscriptions: '/subscriptions',
ayground: '/playground',
er.start(options, ({ port }) => console.log(`Server started, listening on port ${port} for incoming requests.`))
PubSub
See the original documentation in graphql-subscriptions
.
There are three examples demonstrating how to quickly get started with graphql-yoga
:
hello
query.create-react-app
demonstrating how to query data from graphql-yoga
with Apollo Client 2.0.Once your graphql-yoga
server is running, you can use GraphQL Playground out of the box ? typically running on localhost:4000
. (Read here for more information.)
now
To deploy your graphql-yoga
server with now
, follow these instructions:
graphql-yoga
servernow
in your terminalTo deploy your graphql-yoga
server with Heroku, follow these instructions:
heroku login
graphql-yoga
serverheroku create
git push heroku master
up
(Coming soon ? )graphql-yoga
compare to apollo-server
and other tools?As mentioned above, graphql-yoga
is built on top of a variety of other packages, such as graphql.js
, express
and apollo-server
. Each of these provide a certain piece of functionality required for building a GraphQL server.
Using these packages individually incurs overhead in the setup process and requires you to write a lot of boilerplate. graphql-yoga
abstracts away the initial complexity and required boilerplate and let's you get started quickly with a set of sensible defaults for your server configuration.
graphql-yoga
is like create-react-app
for building GraphQL servers.
express
and graphql.js
?graphql-yoga
is all about convenience and a great “Getting Started”-experience by abstracting away the complexity that comes when you're building your own GraphQL from scratch. It's a pragmatic approach to bootstrap a GraphQL server, much like create-react-app
removes friction when first starting out with React.
Whenever the defaults of graphql-yoga
are too tight of a corset for you, you can simply eject from it and use the tooling it's build upon - there's no lock-in or any other kind of magic going on preventing you from this.
express
setup?The core value of graphql-yoga
is that you don't have to write the boilerplate required to configure your express.js application. However, once you need to add more customized behaviour to your server, the default configuration provided by graphql-yoga
might not suit your use case any more. For example, it might be the case that you want to add more custom middleware to your server, like for logging or error reporting.
For these cases, GraphQLServer
exposes the express.Application
directly via its express
property:
er.express.use(myMiddleware())
Middlewares can also be added specifically to the GraphQL endpoint route, by using:
er.express.post(server.options.endpoint, myMiddleware())
Any middlewares you add to that route, will be added right before the apollo-server-express
middleware.
Join our Slack community if you run into issues or have questions. We love talking to you!