Envelop

Envelop is a lightweight library allowing developers to easily develop, sha...

GraphQL
n1ru4l/envelopenvelop.dev@envelop/core

README

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 enrichs the feature set of your application.


@envelop/core: npm version

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


### [Envelop Key Concepts](<(https://www.envelop.dev/docs#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:

  1. ```
  2. yarn add graphql @envelop/core
  3. ```

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

  1. ```ts
  2. import * as GraphQLJS from 'graphql'
  3. import { envelop, useEngine, useSchema } from '@envelop/core'

  5. const mySchema = buildSchema(/* ... */) // GraphQLSchema

  7. const getEnveloped = envelop({
  8.   plugins: [useEngine(GraphQLJS), useSchema(mySchema)]
  9. })
  10. ```

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:

  1. ```ts
  2. const httpServer = createServer()

  4. httpServer.on('request', async (req, res) => {
  5.   // Here you get the alternative methods that are bundled with your plugins
  6.   // You can also pass the "req" to make it available for your plugins or GraphQL context.
  7.   const { parse, validate, contextFactory, execute, schema } = getEnveloped({ req })

  9.   // Parse the initial request and validate it
  10.   const { query, variables } = JSON.parse(req.payload)
  11.   const document = parse(query)
  12.   const validationErrors = validate(schema, document)

  14.   if (validationErrors.length > 0) {
  15.     return res.end(JSON.stringify({ errors: validationErrors }))
  16.   }

  18.   // Build the context and execute
  19.   const context = await contextFactory(req)
  20.   const result = await execute({
  21.     document,
  22.     schema,
  23.     variableValues: variables,
  24.     contextValue: context
  25.   })

  27.   // Send the response
  28.   res.end(JSON.stringify(result))
  29. })

  31. httpServer.listen(3000)
  32. ```

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:

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

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 of each phase, with a flexible API.

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

  1. ```ts
  2. const myPlugin = {
  3.   onExecute({ args }) {
  4.     console.log('Execution started!', { args })

  6.     return {
  7.       onExecuteDone({ result }) {
  8.         console.log('Execution done!', { result })
  9.       }
  10.     }
  11.   }
  12. }

  14. const getEnveloped = envelop({
  15.   plugins: [
  16.     /// ... other plugins ...,
  17.     myPlugin
  18.   ]
  19. })
  20. ```

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're always welcome support from the community.

Code of Conduct


Help us keep Envelop open and inclusive. Please read and follow our [
of Conduct](https://github.com/the-guild-org/Stack/blob/master/CODE_OF_CONDUCT.md) as adopted from Contributor Covenant

License

GitHub license

MIT