Envelop

envelop is a lightweight JavaScript (/TypeScript) library for wrapping GraphQL execution layer and flow, allowing developers to develop, share and collaborate on GraphQL-related plugins while filling the missing pieces in GraphQL implementations.

envelop aims to extend the GraphQL execution flow by adding plugins that enrich the feature set of your application.

@envelop/core:

Envelop is created and maintained by The Guild, and used in production by our clients.

Envelop Key Concepts

• Lightweight
• Wraps the entire GraphQL pipeline, based on plugins
• Low-level API for extending the execution layer
• Agnostic to GraphQL Engine
• Agnostic to the HTTP layer
• Agnostic to the schema tools
• Plugins-based usage
• No vendor lock-in
• Amazing TypeScript support

You can read more about the key concepts or Envelop here

Getting Started

Start by adding the core of Envelop to your codebase:

yarn add graphql @envelop/core

Then, create a simple Envelop based on your GraphQL schema:

1import * as GraphQLJS from 'graphql'
2import { envelop, useEngine, useSchema } from '@envelop/core'
3
4const mySchema = buildSchema(/* ... */) // GraphQLSchema
5
6const getEnveloped = envelop({
7  plugins: [useEngine(GraphQLJS), useSchema(mySchema)]
8})

The result of envelop is a function that allows you to get everything you need for the GraphQL execution: parse, validate, contextBuilder and execute. Use that to run the client's GraphQL queries. Here's a pseudo-code example of how it should look like:

1const httpServer = createServer()
2
3httpServer.on('request', async (req, res) => {
4  // Here you get the alternative methods that are bundled with your plugins
5  // You can also pass the "req" to make it available for your plugins or GraphQL context.
6  const { parse, validate, contextFactory, execute, schema } = getEnveloped({ req })
7
8  // Parse the initial request and validate it
9  const { query, variables } = JSON.parse(req.payload)
10  const document = parse(query)
11  const validationErrors = validate(schema, document)
12
13  if (validationErrors.length > 0) {
14    return res.end(JSON.stringify({ errors: validationErrors }))
15  }
16
17  // Build the context and execute
18  const context = await contextFactory(req)
19  const result = await execute({
20    document,
21    schema,
22    variableValues: variables,
23    contextValue: context
24  })
25
26  // Send the response
27  res.end(JSON.stringify(result))
28})
29
30httpServer.listen(3000)

Behind the scenes, this simple workflow allows you to use Envelop plugins and hook into the entire request handling flow.

Here's a simple example for collecting metrics and logging all incoming requests, using the built-in plugins:

1const getEnveloped = envelop({
2  plugins: [useEngine(GraphQLJS), useSchema(schema), useLogger(), useTiming()]
3})

You can read more about here

Integrations / Examples

You can find the integrations and compatibility list, and code-based examples here

Available Plugins

You can explore all plugins in our Plugins Hub. If you wish your plugin to be listed here and under PluginsHub, feel free to add your plugin information in this file and create a Pull Request!

We provide a few built-in plugins within the @envelop/core, and many more plugins as standalone packages.

Envelop's Plugin Hub

Sharing / Composing envelops

After an envelop has been created, you can share it with others as a complete layer of plugins. This is useful if you wish to create a predefined layer of plugins, and share it with others. You can use it as a shell and as a base for writing shareable pieces of servers.

You can read more about Sharing and Composing Envelops here.

Write your own plugin!

Envelop plugins are just objects with functions, that provide contextual implementation for before/after each phase, with a flexible API.

Here's a simple example that allows you to print the execution params:

1const myPlugin = {
2  onExecute({ args }) {
3    console.log('Execution started!', { args })
4
5    return {
6      onExecuteDone({ result }) {
7        console.log('Execution done!', { result })
8      }
9    }
10  }
11}
12
13const getEnveloped = envelop({
14  plugins: [
15    /// ... other plugins ...,
16    myPlugin
17  ]
18})

For a complete guide and API docs for custom plugins, please refer to Envelop website

Contributing

If this is your first time contributing to this project, please do read our Contributor Workflow Guide before you get started off.

Feel free to open issues and pull requests. We always welcome support from the community.

Code of Conduct

Help us keep Envelop open and inclusive. Please read and follow our Code of Conduct as adopted from Contributor Covenant

License

MIT