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 enrichs the feature set of your application.
@envelop/core:
Envelop is created and maintained by The Guild, and used in production by our clients.
- 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 log 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
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.
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.
Envelop plugins are just objects with functions, that provide contextual implementation for before/after of 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
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're always welcome support from the community.
Help us keep Envelop open and inclusive. Please read and follow our of Conduct as adopted from Contributor Covenant
MIT