|
1 | | -[](https://graphql.org/conf/2024/?utm_source=github&utm_medium=envelop&utm_campaign=readme) |
2 | | - |
3 | 1 | ## Envelop |
4 | 2 |
|
5 | 3 | `envelop` is a lightweight JavaScript (/TypeScript) library for wrapping GraphQL execution layer and |
6 | 4 | flow, allowing developers to develop, share and collaborate on GraphQL-related plugins while filling |
7 | 5 | the missing pieces in GraphQL implementations. |
8 | 6 |
|
9 | | -`envelop` aims to extend the GraphQL execution flow by adding plugins that enrich the feature set of |
10 | | -your application. |
11 | | - |
12 | | -<p align="center"> |
13 | | - <img height="150" src="./logo.png"> |
14 | | -</p> |
15 | | - |
16 | | -`@envelop/core`: |
17 | | -[](https://www.npmjs.com/package/@envelop/core) |
18 | | - |
19 | | -> Envelop is created and maintained by [The Guild](https://the-guild.dev/), and used in production |
20 | | -> by our clients. |
21 | | -
|
22 | | -### [Envelop Key Concepts](<(https://www.envelop.dev/docs#key-concepts)>) |
23 | | - |
24 | | -- Lightweight |
25 | | -- Wraps the entire GraphQL pipeline, based on plugins |
26 | | -- Low-level API for extending the execution layer |
27 | | -- Agnostic to GraphQL Engine |
28 | | -- Agnostic to the HTTP layer |
29 | | -- Agnostic to the schema tools |
30 | | -- Plugins-based usage |
31 | | -- No vendor lock-in |
32 | | -- Amazing TypeScript support |
33 | | - |
34 | | -[You can read more about the key concepts or Envelop here](https://www.envelop.dev/docs#key-concepts) |
35 | | - |
36 | | -## [Getting Started](https://www.envelop.dev/docs/getting-started) |
37 | | - |
38 | | -Start by adding the core of Envelop to your codebase: |
39 | | - |
40 | | -``` |
41 | | -yarn add graphql @envelop/core |
42 | | -``` |
43 | | - |
44 | | -Then, create a simple Envelop based on your GraphQL schema: |
45 | | - |
46 | | -```ts |
47 | | -import * as GraphQLJS from 'graphql' |
48 | | -import { envelop, useEngine, useSchema } from '@envelop/core' |
49 | | - |
50 | | -const mySchema = buildSchema(/* ... */) // GraphQLSchema |
51 | | - |
52 | | -const getEnveloped = envelop({ |
53 | | - plugins: [useEngine(GraphQLJS), useSchema(mySchema)] |
54 | | -}) |
55 | | -``` |
56 | | - |
57 | | -The result of `envelop` is a function that allows you to get everything you need for the GraphQL |
58 | | -execution: `parse`, `validate`, `contextBuilder` and `execute`. Use that to run the client's GraphQL |
59 | | -queries. Here's a pseudo-code example of how it should look like: |
60 | | - |
61 | | -```ts |
62 | | -const httpServer = createServer() |
63 | | - |
64 | | -httpServer.on('request', async (req, res) => { |
65 | | - // Here you get the alternative methods that are bundled with your plugins |
66 | | - // You can also pass the "req" to make it available for your plugins or GraphQL context. |
67 | | - const { parse, validate, contextFactory, execute, schema } = getEnveloped({ req }) |
68 | | - |
69 | | - // Parse the initial request and validate it |
70 | | - const { query, variables } = JSON.parse(req.payload) |
71 | | - const document = parse(query) |
72 | | - const validationErrors = validate(schema, document) |
73 | | - |
74 | | - if (validationErrors.length > 0) { |
75 | | - return res.end(JSON.stringify({ errors: validationErrors })) |
76 | | - } |
77 | | - |
78 | | - // Build the context and execute |
79 | | - const context = await contextFactory(req) |
80 | | - const result = await execute({ |
81 | | - document, |
82 | | - schema, |
83 | | - variableValues: variables, |
84 | | - contextValue: context |
85 | | - }) |
86 | | - |
87 | | - // Send the response |
88 | | - res.end(JSON.stringify(result)) |
89 | | -}) |
90 | | - |
91 | | -httpServer.listen(3000) |
92 | | -``` |
93 | | - |
94 | | -Behind the scenes, this simple workflow allows you to use **Envelop plugins** and hook into the |
95 | | -entire request handling flow. |
96 | | - |
97 | | -Here's a simple example for collecting metrics and logging all incoming requests, using the built-in |
98 | | -plugins: |
99 | | - |
100 | | -```ts |
101 | | -const getEnveloped = envelop({ |
102 | | - plugins: [useEngine(GraphQLJS), useSchema(schema), useLogger(), useTiming()] |
103 | | -}) |
104 | | -``` |
105 | | - |
106 | | -> [You can read more about here](https://www.envelop.dev/docs/getting-started) |
107 | | -
|
108 | | -## [Integrations / Examples](https://www.envelop.dev/docs/integrations) |
109 | | - |
110 | | -[You can find the integrations and compatibility list, and code-based examples here](https://www.envelop.dev/docs/integrations) |
111 | | - |
112 | | -## Available Plugins |
113 | | - |
114 | | -You can explore all plugins in our [Plugins Hub](https://www.envelop.dev/plugins). If you wish your |
115 | | -plugin to be listed here and under PluginsHub, feel free to add your plugin information |
116 | | -[in this file](https://github.com/graphql-hive/envelop/edit/main/website/src/lib/plugins.ts#L23) and |
117 | | -create a Pull Request! |
118 | | - |
119 | | -We provide a few built-in plugins within the `@envelop/core`, and many more plugins as standalone |
120 | | -packages. |
121 | | - |
122 | | -**[Envelop's Plugin Hub](https://www.envelop.dev/plugins)** |
123 | | - |
124 | | -## Sharing / Composing `envelop`s |
125 | | - |
126 | | -After an `envelop` has been created, you can share it with others as a complete layer of plugins. |
127 | | -This is useful if you wish to create a predefined layer of plugins, and share it with others. You |
128 | | -can use it as a shell and as a base for writing shareable pieces of servers. |
129 | | - |
130 | | -You can read more about |
131 | | -[Sharing and Composing Envelops here](https://www.envelop.dev/docs/composing-envelop). |
132 | | - |
133 | | -## Write your own plugin! |
134 | | - |
135 | | -Envelop plugins are just objects with functions, that provide contextual implementation for |
136 | | -before/after each phase, with a flexible API. |
137 | | - |
138 | | -Here's a simple example that allows you to print the execution params: |
139 | | - |
140 | | -```ts |
141 | | -const myPlugin = { |
142 | | - onExecute({ args }) { |
143 | | - console.log('Execution started!', { args }) |
144 | | - |
145 | | - return { |
146 | | - onExecuteDone({ result }) { |
147 | | - console.log('Execution done!', { result }) |
148 | | - } |
149 | | - } |
150 | | - } |
151 | | -} |
152 | | - |
153 | | -const getEnveloped = envelop({ |
154 | | - plugins: [ |
155 | | - /// ... other plugins ..., |
156 | | - myPlugin |
157 | | - ] |
158 | | -}) |
159 | | -``` |
160 | | - |
161 | | -[For a complete guide and API docs for custom plugins, please refer to Envelop website](https://www.envelop.dev/docs/plugins) |
162 | | - |
163 | | -### Contributing |
164 | | - |
165 | | -If this is your first time contributing to this project, please do read our |
166 | | -[Contributor Workflow Guide](https://github.com/the-guild-org/Stack/blob/master/CONTRIBUTING.md) |
167 | | -before you get started off. |
168 | | - |
169 | | -Feel free to open issues and pull requests. We always welcome support from the community. |
170 | | - |
171 | | -### Code of Conduct |
172 | | - |
173 | | -Help us keep Envelop open and inclusive. Please read and follow our |
174 | | -[Code of Conduct](https://github.com/the-guild-org/Stack/blob/master/CODE_OF_CONDUCT.md) as adopted |
175 | | -from [Contributor Covenant](https://www.contributor-covenant.org/) |
176 | | - |
177 | | -### License |
178 | | - |
179 | | -[](https://raw.githubusercontent.com/graphql-hive/envelop/master/LICENSE) |
180 | | - |
181 | | -MIT |
| 7 | +[Moved to GraphQL Yoga repository](https://github.com/graphql-hive/graphql-yoga/blob/main/packages/envelop/README.md) |
0 commit comments