• v3
  • Migration
  • Yoga v2

Install the new NPM package

Now GraphQL Yoga has a single NPM package for all environments graphql-yoga instead of @graphql-yoga/common and @graphql-yoga/node. So you need to uninstall @graphql-yoga/common and @graphql-yoga/node then install graphql-yoga from NPM.import from '@theguild/components';

yarn add graphql-yoga

createServer renamed to createYoga

In order to prevent the confusion, we decided to rename createServer function to createYoga.

- import { createServer } from '@graphql-yoga/node'
+ import { createYoga } from 'graphql-yoga'
import { schema } from './schema';
 
- const yoga = createServer({
+ const yoga = createYoga({
     schema,
 })

handleIncomingMessage renamed to handleNodeRequest

For some frameworks, we need to use this low-level function such as Fastify and Koa. So you can basically rename the method to handleNodeRequest.

No more .start and .stop

Previously on Node and CF/Service Workers environments, Yoga handles server processes with .start and .stop methods together with some environment specific server configurations. Yoga no longer deals with HTTP server configuration so the following changes needed;

For Node

- import { createServer } from '@graphql-yoga/node'
+ import { createYoga } from 'graphql-yoga'
+ import { createServer } from 'http'
 
- const server = createServer({
-     port: 4000,
-     hostname: '127.0.0.1'
- })
+ const yoga = createYoga({})
+ const server = createServer(yoga)
 
- server.start()
+ server.listen(4000, '127.0.0.1')

For CF/Service Workers

- yoga.start()
+ self.addEventListener('fetch', yoga)

No more Node specific multipart configuration

Previously it was possible to configure limitations of multipart request processing in @graphql-yoga/node package but now graphql-yoga package is completely platform agnostic and we avoid to have any Node specific configuration in GraphQL Yoga. But it is still possible to keep the same behavior by configuring @whatwg-node/fetch which is used by GraphQL Yoga internally for Node.js.

- import { createServer } from '@graphql-yoga/node'
+ import { createYoga } from 'graphql-yoga'
+ import { createFetch } from '@whatwg-node/fetch'
 
- const yoga = createServer({
+ const yoga = createYoga({
+  fetchAPI: createFetch({
+     // We prefer `node-fetch` over `undici` and current unstable Node's implementation
+     useNodeFetch: true,
+     formDataLimits: {
-  multipart: {
      // Maximum allowed file size (in bytes)
      fileSize: 1000000,
      // Maximum allowed number of files
      files: 10,
      // Maximum allowed size of content (operations, variables etc...)
      fieldSize: 1000000,
      // Maximum allowed header size for form data
      headerSize: 1000000,
    },
+  }),
})

endpoint and graphiql.endpoint options are now removed In v2, there is endpoint option which is used to configure the GraphQL endpoint, and graphiql.endpoint to point GraphiQL to a different GraphQL API. Now they are removed in favor graphqlEndpoint option. If you want to use YogaGraphiQL for a different GraphQL endpoint, you can use @graphql-yoga/render-graphiql package seperately.

- import { createServer } from '@graphql-yoga/node'
+ import { createYoga } from 'graphql-yoga'
- createServer({
+ createYoga({
-  endpoint: '/mypath',
-  graphiql: {
-    endpoint: '/mypath',
-  },
+  graphqlEndpoint: '/mypath',
})

You need to define graphqlEndpoint if your GraphQL endpoint is not /graphql

For example, if you use Next.js or Sveltekit, you probably use /api/graphql or /api/somethingelse which is not /graphql. In v3, you need to tell Yoga explicitly what is your GraphQL endpoint.

- import { createServer } from '@graphql-yoga/node'
+ import { createYoga } from 'graphql-yoga'
- createServer({
+ createYoga({
+  graphqlEndpoint: '/api/graphql',
})

** No more GraphQLYogaError so you can use GraphQLError instead **

In v2, we introduced a new error class GraphQLYogaError which is a subclass of GraphQLError and it is now deprecated in favor of GraphQLError. So in resolvers, you can use it in the same way but the second parameter of GraphQLError constructor is not extensions but an object that contains more options for GraphQLError. You can basically do the following change;

- import { GraphQLYogaError } from '@graphql-yoga/node'
+ import { GraphQLError } from 'graphql'
 
- const myError = new GraphQLYogaError('My error message', {
+ const myError = new GraphQLError('My error message', {
+  extensions: {
    code: 'MY_CODE',
    myCustomField: 'myCustomValue',
+  },
})

Also you can change the status code and headers of the error response by using the extensions object.

new GraphQLError('My error message', {
  extensions: {
    code: 'NOT_LOGGED_IN',
    message: 'You need to be logged in to do this',
    http: {
      status: 401,
      headers: {
        'X-Custom-Header': 'my-custom-value',
      },
    },
  },
})
Last updated on September 20, 2022