The Guild LogoThe Guild Monogram
Envelop Logo

Envelop

Get Started

Building Plugins#

When getting started with Envelop, you may not have to build your own plugins. There is a high probability the functionality you seek has already been implemented and is available on the Envelop Plugin Hub.

Specific logic related to your organizations business needs, might require you to implement your own plugin from scratch. The simple Envelop plugin API allows you to solve your problems in a structured and reusable way.

The plugin interface#

Envelop plugins are objects with handler functions that provide a contextual implementation for running logic before and after each phase, with a flexible API.

If you are using TypeScript, you can import the Plugin interface from @envelop/core package, for getting full type-safety while building envelop plugins.

All plugins share the common plugin interface that can be found on GitHub.

https://github.com/n1ru4l/envelop/blob/main/packages/types/src/plugin.ts

Building your first plugin#

Here's a simple example that allows you to print the execution and parsing parameter.

import type { Plugin } from '@envelop/core' const myPlugin: Plugin = { onParse({ params }) { console.log('Parse started!', { params }) return result => { console.log('Parse done!', { result }) } }, onExecute({ args }) { console.log('Execution started!', { args }) return { onExecuteDone: ({ result }) => { console.log('Execution done!', { result }) } } } } const getEnveloped = envelop({ plugins: [ /// ... other plugins ..., myPlugin ] })

Adding config options to your plugin#

Often plugins require additional configurartion. A common pattern for doing this is by creating a factor function that returns a Plugin.

const myPlugin = (shouldPrintResult: boolean): Plugin => { return { onExecute({ args }) { console.log('Execution started!', { args }) if (shouldPrintResult) { return { onExecuteDone: ({ result }) => { console.log('Execution done!', { result }) } } } } } } const getEnveloped = envelop({ plugins: [ /// ... other plugins ..., myPlugin(true) ] })

Sharing Envelop plugins#

In case you want to publish a standalone envelop plugin as a npm package we recommend using @envelop/core as a peerDependency. By doing so we can reduce the likelyhood of @envelop/core being instanciated multiple times due a version mismatch and leading to unexpected behaviours.

The existing envelop plugins within the envelop monorepo serve as a good example. The @envelop/preload-assets plugin is a simple example on how to setup a plugin package.