title |
---|
What is Envelop? |
envelop
is a lightweight JavaScript (/TypeScript) library for customizing the GraphQL execution layer and flow, allowing developers to build, 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.
The envelop
plugins are small, reusable, shareable pieces of code, that can be shipped as NPM packages, or inlined within your codebase.
As an application developer, you can leverage envelop
plugins to customize your GraphQL execution flow, based on your needs.
As as plugin developer, you get an standardized interface for sharing your plugins with others.
The envelop
plugins are hooking into specific phases within the GraphQL execution pipeline, and can alter each phase based on your needs.
With
envelop
, you can easily wrap your common logic, and share it with others.
The core of envelop
has zero dependencies and will only alter your GraphQL execution based on the plugins you wish to use.
It can be integrated with any GraphQL server that follows the execution phase, as defined in the GraphQL specification and lets you provide your own lifecycle methods.
envelop
wraps the entire pipeline of the GraphQL operation execution, so developers can hook into all the phases - parse
, validate
, context building, execute
and more.
By offering hooks for the entire pipeline, we allow developers to create plugins that add complete features to your GraphQL pipeline, without creating spaghetti code, or code that is specific to your application.
Here is a breakdown of a few envelop
plugins, and an explanation of how each of them contribute to the execution pipeline:
useLogger
- hooks into "before" of all phases, and prints the execution parameters to the console usingconsole.log
.useTiming
- hooks into "before" and "after" of all phases, measures times, and then prints them.useParserCache
- hooks into "before" and "after" of theparse
phase and implements caching based on the operation string.useGraphQLJit
- hooks intoexecute
phase and replaces theexecute
function with GraphQL-Jit’s executor.usePersistedOperations
- hooks intoparse
and replaces theparse
function with a function that maps a hash into a DocumentNode.useGenericAuth
- hooks into context building and resolves the current user from the GraphQL request, then hooks into theexecute
phase to verify the users identity.useOpenTelemetry
- hooks into all phases, execution and resolvers, and creates Spans for OpenTelemetry tracing.
We do not aim to provide a complete, vendor lock-in suite, since we believe that developers should be able to adjust and replace any part of their application, at any time, without major implications or refactoring.
The core implementation of envelop
is agnostic to the HTTP server you use, and agnostic to the way your define your GraphQL Schema, so it is not a traditional "server" framework. Envelop plugins should be developed framework agnostic.
However, you can still create plugins that include specific logic for your HTTP server - or your schema framework, if necessary.
Envelop can be used with any environment (Node.js or browser) and any GraphQL workflow (client/server, client-side, or server-to-server).
Separating the execution workflow and the logic that it runs in each phase allows you to write reusable pieces of code.
By using plugins that extends your GraphQL execution, you can very easily add features like:
- Logging
- Metric collection
- Error handling
- Custom validations
- Resolvers tracing
- Authentication
- Authorization
And much more, without having to write it explicitly every time for every project or microservice.
Often, developers are looking for a way to reuse their server setup as a boilerplate/template with minimal effort.
Envelop allows you to create Envelops instances that can be shared easily.
If you are working in a microservice environment, or in an enterprise environment with many servers - you can now share the entire base GraphQL setup in envelop plugins, and extend each of the servers based on your needs.