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
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:
import * as GraphQLJS from 'graphql'
import { envelop, useEngine, useSchema } from '@envelop/core'
const mySchema = buildSchema(/* ... */) // GraphQLSchema
const getEnveloped = envelop({
plugins: [useEngine(GraphQLJS), useSchema(mySchema)]
})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:
const httpServer = createServer()
httpServer.on('request', async (req, res) => {
// Here you get the alternative methods that are bundled with your plugins
// You can also pass the "req" to make it available for your plugins or GraphQL context.
const { parse, validate, contextFactory, execute, schema } = getEnveloped({ req })
// Parse the initial request and validate it
const { query, variables } = JSON.parse(req.payload)
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 context = await contextFactory(req)
const result = await execute({
document,
schema,
variableValues: variables,
contextValue: context
})
// Send the response
res.end(JSON.stringify(result))
})
httpServer.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:
const getEnveloped = envelop({
plugins: [useEngine(GraphQLJS), useSchema(schema), useLogger(), useTiming()]
})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.
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:
const myPlugin = {
onExecute({ args }) {
console.log('Execution started!', { args })
return {
onExecuteDone({ result }) {
console.log('Execution done!', { result })
}
}
}
}
const getEnveloped = envelop({
plugins: [
/// ... other plugins ...,
myPlugin
]
})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