The Guild LogoThe Guild Monogram
Envelop Logo


Get Started

First Steps#

Using Envelop is straight-forward and intuitive, in this section you will lean how to install and set up an GraphQL server using Envelop from scratch.

In case you are being referred to the Envelop documentation from a framework or library that implements envelop, you can straight dive into the Plugin Hub or head over to the Plugin Tutorial for learning how to write your own plugins.


Start by adding the core of envelop and graphql to your codebase.

yarn add graphql @envelop/core

Create your first envelop#

After installing the @envelop/core package, you can use the envelop function for creating your getEnveloped function. We use a simple GraphQL schema that we build with the buildSchema function from graphql.

import { envelop, useSchema } from '@envelop/core'; import { buildSchema } from 'graphql'; const schema = buildSchema(/* GraphQL */ ` type Query { hello: String } `); export const getEnveloped = envelop({ plugins: [useSchema(schema)], });

Use your envelop#

The result of envelop is a factory function that allows you to get everything you need for the GraphQL execution: parse, validate, contextBuilder, execute and subscribe. It is usually named getEnveloped.

By calling the getEnveloped function you will get all the primitive functions required for the GraphQL execution layer.

// prettier-ignore const { contextFactory, parse, validate, execute, subscribe, schema, } = getEnveloped()

Add plugins to your envelop#

After you set up your base envelop, you can start customizing your GraphQL server. Adding new functionality is as easy as adding a new envelop plugin to your base envelop setup.

Let's add a parser and validation cache, so sending the same operation string sent to our server is cached using a LRU cache, allowing to improve the overall performance of the GraphQL execution layer.

yarn add @envelop/parser-cache @envelop/validation-cache
import { envelop, useSchema } from '@envelop/core'; import { buildSchema } from 'graphql'; import { useParserCache } from '@envelop/parser-cache'; import { useValidationCache } from '@envelop/validation-cache'; const schema = buildSchema(/* GraphQL */ ` type Query { hello: String } `); const getEnveloped = envelop({ plugins: [ // all enabled plugins useSchema(schema), useParserCache(), useValidationCache(), ], });

A list of all available plugins can be found on the Envelop Plugin Hub.

Use your envelop with an HTTP server#

you can build a very simple GraphQL HTTP server from scratch, by using the Node.js http module and only these functions.

import { createServer } from 'http'; import { GraphQLError } from 'graphql'; import { getEnveloped } from './envelop'; const httpServer = http.createServer(async (req, res) => { try { // body parsing req.body = await new Promise((resolve, reject) => { let data = ''; req.on('data', chunk => { data += String(chunk); }); req.on('end', () => { resolve(data); }); req.on('error', err => reject(err)); }); const { // Get the GraphQL execution functions with attached plugin handlers parse, validate, contextFactory, execute, schema, // pass in an initial context that all plugins can consume and extend } = getEnveloped({ req }); // Parse request body JSON const { query, variables } = JSON.parse(req.body); const document = parse(query); const validationErrors = validate(schema, document); if (validationErrors.length > 0) { return res.end(JSON.stringify({ errors: validationErrors })); } // Build the context and execute const contextValue = await contextFactory(); const result = await execute({ document, schema, variableValues: variables, contextValue, }); // Send the response res.end(JSON.stringify(result)); } catch (err) { if (err instanceof GraphQLError === false) { err = new GraphQLError(err.message); } res.end(JSON.stringify({ errors: [err] })); } }); httpServer.listen(3000);

After starting this server we can send a GraphQL operation using curl, yielding a response of {"data":{"__typename":"Query"}}.

curl \ -X POST \ -d '{"query":"{__typename}"}' \ http://localhost:3000

This example uses the Node.js http module and is a very simplified handler that does not strictly follow the GraphQL over HTTP specification as it does not handle headers or respect HTTP methods. For actual production usage we recommend using Envelop with one of the popular and battle-tested HTTP frameworks and servers. Check the examples on our Integrations page.