--- title: Writing plugins description: Guide for writing plugins for Pothos --- Writing plugins for Pothos may seem a little intimidating at first, because the types used by Pothos are fairly complex. Fortunately, for many types of plugins, the process is actually pretty easy, once you understand the core concepts of how Pothos's type system works. Don't worry if the descriptions don't make complete sense at first. Going through the examples in this guide will hopefully make things seem a lot easier. This guide aims to cover a lot of the most common use cases for creating plugins, but does not contain full API documentation. Exploring the types or source code to see what all is available is highly encouraged, but should not be required for most use cases. ## The type system Pothos has 2 main pieces to its type system: 1. `PothosSchemaTypes`: A global namespace for shared types 2. `SchemaTypes`: A collection of types passed around through Generics specific to each instance of `SchemaBuilder` ### `PothosSchemaTypes` The `PothosSchemaTypes` contains interfaces for all the various options objects used throughout the API, along with some other types that plugins may want to extend. Each of the interfaces can be extended by a plugin to add new options. Each interface takes a number of relevant generic parameters that can be used to make the options more useful. For example, the interface for field options will be passed the shape of the parent, the expected return type, and any arguments. ### `SchemaTypes` The `SchemaTypes` type is based on the Generic argument passed to the `SchemaBuilder`, and extended with reasonable defaults. Almost every interface in the `PothosSchemaTypes` will have access to it \(look for `Types extends SchemaTypes` in the generics of almost any interface\). This Type contains the types for Scalars, backing models for some object and interface types, and many custom properties from various plugins. If your plugin needs the user to provide some types that will be shared across the whole schema, this is how you will be able to access them when adding fields to the options objects defined in `PothosSchemaTypes`. ## Getting Started The best place to start is by looking through the [example plugin](https://github.com/hayes/pothos/tree/main/packages/plugin-example). The general structure of a plugin has 3 main parts: 1. `index.ts` which contains a plugin's actual implementation 2. `global-types.ts` which contains any additions to Pothos's built in types. 3. `types.ts` which should contain any types that do NOT belong to the global `PothosSchemaTypes` namespace. To get set up quickly, you can copy these files from the example plugin to suit your needs. The first few things to change are: 1. The plugin name in `index.ts` 2. The name of the Plugin class in `index.ts` 3. The name key/name for the plugin in the `Plugins` interface in `global-types.ts` After setting up the basic layout of your plugin, I recommend starting by defining the types for your plugin first \(in `global-types.ts`\) and setting up a test schema that uses your plugin. This allows you to get the user facing API for your plugin working first, so you can see that any new options you add to the API are working as expected, and that any type constraints are enforced correctly. Once you are happy with your API, you can start building out the functionality in index.ts. Building the types first also make the implementation easier because the properties you will need to access in your extension may not exist on the config objects until you have defined your types. ### `global-types.ts` `global-types.ts` must contain the following: 1. A declaration of the `PothosSchemaTypes` namespace ```typescript declare global { export namespace PothosSchemaTypes {} } ``` 2. An addition to the `Plugins` interface that maps the plugin name, to the plugin type \(this needs to be inside the `PothosSchemaTypes` namespace\) ```typescript export interface Plugins { example: PothosExamplePlugin; } ``` `global-types.ts` should NOT include definitions that do not belong to the `PothosSchemaTypes` namespace. Types for your plugin should be added to a separate `types.ts` file, and imported as needed into `global-types.ts`. To add properties to the various config objects used by the `SchemaBuilder`, you should start by finding the interface that defines that config object in `@pothos/core`. Currently there are 4 main files that define the types that make up `PothosSchemaTypes` namespace. 1. [`type-options.ts`](https://github.com/hayes/pothos/blob/main/packages/core/src/types/global/type-options.ts): Contains the interfaces that define the options objects for the various types \(Object, Interface, Enum, etc\). 2. [`field-options.ts`](https://github.com/hayes/pothos/blob/main/packages/core/src/types/global/field-options.ts): Contains the interfaces that define the options objects for creating fields 3. [`schema-types.ts`](https://github.com/hayes/pothos/blob/main/packages/core/src/types/global/schema-types.ts): Contains the interfaces for SchemaBuilder options, SchemaTypes, options for `toSchema`, and other utility interfaces that may be useful for plugins to extend that do not fall into one of the other categories. 4. [`classes.ts`](https://github.com/hayes/pothos/blob/main/packages/core/src/types/global/classes.ts): Contains interfaces that describe the classes used by Pothos, include `SchemaBuilder` and the various field builder classes. Once you have identified a type you wish to extend, copy it into the `PothosSchemaTypes` namespace in your `global-types.ts`, but remove all the existing properties. You will need to keep all the Generics used by the interface, and should import the types used in generics from `@pothos/core`. You can now add any new properties to the interface that your plugin needs. Making new properties optional \(`newProp?: TypeOfProp`\) is recommended for most use cases. ## `index.ts` `index.ts` must contain the following: 1. A bare import of the global types \(`import './global-types';`\) 2. The plugins name, which should be typed as a string literal rather than as a generic string: `const pluginName = 'example'` 3. A default export of the plugin name `export default pluginName` 4. A class that extends BasePlugin: `export class PothosExamplePlugin extends BasePlugin {}` `BasePlugin` and `SchemaTypes` can both be imported from `@pothos/core` 5. A call to register the plugin: `SchemaBuilder.registerPlugin(pluginName, PothosExamplePlugin);` `SchemaBuilder` can also be imported from `@pothos/core` ### Run a complete plugin The example adds a `logLabel` builder option, registers a local plugin, and wraps each resolver. The query logs two field resolutions. The request counter starts at one for each execution because it receives a fresh context; `logLabel` labels the messages. playground-examples/architecture-writing-plugin/plugin.ts#plugin The plugin is registered before it is passed to the builder: playground-examples/architecture-writing-plugin/plugin.ts#registration Open `global-types.ts` to see the plugin name and `logLabel` option added to `PothosSchemaTypes`. The query includes synchronous and asynchronous resolvers; the wrapper returns their values unchanged. The sections below link runnable hooks to complete examples. Interface declarations describe the types to merge into `PothosSchemaTypes`; they are reference fragments rather than independent schemas. Subscription hooks need a runtime that executes subscriptions. ### Life cycle hooks The `SchemaBuilder` will instantiate plugins each time the `toSchema` method is called on the builder. As the schema is built, it will invoke the various life cycle methods on each plugin if they have been defined. To hook into each lifecycle event, simply define the corresponding function in your plugin class. For the exact function signature, see the `index.ts` of the example plugin. - `onTypeConfig`: Invoked for each type, with the config object that will be used to construct the underlying GraphQL type. - `onOutputFieldConfig`: Invoked for each Object, or Interface field, with the config object describing the field. - `onInputFieldConfig`: Invoked for each InputObject field, or field argument, with the config object describing the field. - `onEnumValueConfig`: Invoked for each value in an enum - `beforeBuild`: Invoked before building schemas, last chance to add new types or fields. - `afterBuild`: Invoked with the fully built Schema. - `wrapResolve`: Invoked when creating the resolver for each field - `wrapSubscribe`: Invoked for each field in the `Subscriptions` object. - `wrapArgMappers`: Wraps outside argument mapping for resolvers and subscription setup; see [Argument mapping and errors](#argument-mapping-and-errors). - `wrapResolveType`: Invoked for each Union and Interface. - `wrapIsTypeOf`: Invoked for each Object, including objects without an `isTypeOf` function. Each of the lifecycle methods above \(except `beforeBuild`\) expect a return value that matches their first argument \(either a config object, or the resolve/subscribe/resolveType function\). If your plugin does not need to modify these values, it can simply return the value that was passed in. When your plugin does need to change one of the config values, you should return a copy of the config object with your modifications, rather than modifying the config object that was passed in. This can be done by either using `Object.assign`, or spreading the original config into a new object `{...originalConfig, newProp: newValue }`. Inherited interface fields have a separate output field config for each owning object or interface. `onOutputFieldConfig` runs once for each declaration and owner pair in a schema build. On an inherited field, `parentType` names the owner and `declaringType` names the interface that originally declared the field. Arguments also have their own configs with the owner's `parentType`. `kind` and `graphqlKind` still describe the field builder that declared the field, so plugin-specific field options keep their original meaning. Resolver and subscriber wrappers receive the owner's config. Plugins that generate shared output types for interface fields must use `config.declaringType ?? config.parentType` for the generated type's identity. Generating a different union for each owner would make the object field incompatible with the interface field. Plugins that apply type-level behavior should use `parentType` to look up the owner. Each config object will have the properties expected by the GraphQL for creating the types or fields \(although some properties like `resolve` will be added later\), but will also include a number of Pothos specific properties. These properties include `graphqlKind` to indicate what kind of GraphQL type the config object is for, `pothosOptions`, which contains all the options passed in to the schema builder when creating the type or field. If your plugin needs to add additional types or fields to the schema it should do this in the `beforeBuild` hook. Any types added to the schema after this, may not be included correctly. Plugins should also account for the fact that a new instance of the plugin will be created each time the schema is called, so any types or fields added to the schema should only be applied once \(per builder\), even if multiple instances of the plugin are created. To help with this, there is a `runUnique` helper on the base plugin class, which accepts a key, and a callback, and will only run a callback once per builder for the given key, even across multiple `toSchema` calls. The example calls `toSchema()` twice, but the preparation callback runs only once: playground-examples/architecture-plugin-hooks/plugin.ts#before-build ## Use cases Below are a few of the most common use cases for how a plugin might extend the Pothos with very simplified examples. Most plugins will likely need a combination of these strategies, and some uses cases may not be well documented. If you are unsure about how to solve a specific problem, feel free to open a GitHub Issue for more help. In the examples below, when "extending an interface", the interface should be added to the `PothosSchemaTypes` namespace in `global-types.ts`. ### Adding options to the SchemaBuilder constructor You may have noticed that plugins are not instantiated by the user, and therefore users can't pass options directly into your plugin when creating it. Instead, the recommended way to configure your plugin is by contributing new properties to the options object passed to the SchemaBuilder constructor. This can be done by extending the `SchemaBuilderOptions` interface. ```typescript export interface SchemaBuilderOptions { optionInRootOfConfig?: boolean; nestedOptionsObject?: ExamplePluginOptions; // imported from types.ts } ``` Extending this interface will allow the user to pass in these new options when creating an instance of `SchemaBuilder`. You can then access the options through `this.builder.options` in your plugin, with everything correctly typed. The example reflects `nestedOptionsObject.exampleOption` in the object description: playground-examples/architecture-plugin-hooks/plugin.ts#constructor-options ### Adding options when building a schema \(`toSchema`\) In some cases, your plugin may be designed for schemas that be built in different modes. For example the mocks plugin allows the schema to be built repeatedly with different sets of mocks, or the subGraph allows building a schema multiple times to generate separate subgraphs. For these cases, you can extend the options passed to `toSchema` instead: ```typescript export interface BuildSchemaOptions { customBuildTimeOptions?: boolean; } ``` These options can be accessed through `this.options` in your plugin: playground-examples/architecture-plugin-hooks/plugin.ts#build-options ### Adding options to types Each GraphQL type has its own options interface which can be extended. For example, to extend the options for creating an Object type: ```typescript export interface ObjectTypeOptions { optionOnObject?: boolean; } ``` These options can then be accessed in your plugin when you receive the config for the type: playground-examples/architecture-plugin-hooks/plugin.ts#type-options In the example above, we need to check `typeConfig.kind` to ensure that the type config is for an object. Without this check, typescript will not know that the config object is for an object, and will not let us access the property. `typeConfig.kind` corresponds to how Pothos splits up Types for its config objects, meaning that it has separate `kind`s for `Query`, `Mutation`, and `Subscription` even though these are all `Objects` in GraphQL terminology. The `typeConfig.graphqlKind` can be used to get the actual GraphQL type instead. ### Adding options to fields Similar to Types, fields also have a number of interfaces that can be extended to add options to various types of fields: ```typescript export interface MutationFieldOptions< Types extends SchemaTypes, Type extends TypeParam, Nullable extends FieldNullability, Args extends InputFieldMap, ResolveReturnShape, > { customMutationFieldOption?: boolean; } ``` Field interfaces have a few more generics than other interfaces we have looked at. These generics can be used to make the options you add more specific to the field currently being defined. It is important to copy all the generics of the interfaces as they are defined in `@pothos/core` even if you do not use the generics in your own properties. If the generics do not match, typescript won't be able to merge the definitions. You do NOT need to include the `extends` clause of the interface, if the interface extends another interface \(like `FieldOptions`\). Similar to Type options, Field options will be available in the fieldConfigs in your plugin, once you check that the fieldConfig is for the correct `kind` of field. playground-examples/architecture-plugin-hooks/plugin.ts#field-options ### Adding new methods on builder classes Adding new methods to `SchemaBuilder` or one of the `FieldBuilder` classes is also done through extending interfaces. Extending these interfaces is how typescript is able to know these methods exist, even though they are not defined on the original classes. ```typescript export interface SchemaBuilder { buildCustomObject: () => ObjectRef; } ``` The above is a simple example of defining a new `buildCustomObject` method that takes no arguments, and returns a reference to a new custom object type. Defining this type will not work on its own, and we still need to define the actual implementation of this method. This might look like: playground-examples/architecture-plugin-hooks/plugin.ts#builder-method Note that the above function does NOT use an arrow function, so that the function can access `this` as a reference to the SchemaBuilder instance. ### Wrapping resolvers to add runtime functionality Some plugins will need to add runtime behavior. There are a few lifecycle hooks for wrapping `resolve`, `subscribe`, and `resolveType`. These hooks will receive the function they are wrapping, along with a config object for the field or type they are associated with, and should return either the original function, or a wrapper function with the same API. It is important to remember that resolvers can resolve values in a number of ways \(normal values, promises, or even something as complicated `Promise<(Promise | T)[]>`. So be careful when using a wrapper that introspected the return value of a resolve function. Plugins should only wrap resolvers when absolutely necessary. playground-examples/architecture-writing-plugin/plugin.ts#plugin ### Transforming a schema For some plugins the other provided lifecycle hooks may not be sufficiently powerful to modify the schema in all the ways a plugin may want. For example removing types from the schema \(eg. the `SubGraph` plugin\). In these cases, the `afterBuild` hook can be used. It receives the built schema, and is expected to return either the schema it was passed, or a completely new schema. This allows plugins to use 3rd party libraries like `graphql-tools` to arbitrarily transform schemas if desired. This example returns a new schema with a changed description. The changed description is available through `__schema.description`: playground-examples/architecture-plugin-hooks/plugin.ts#after-build ### Using SchemaTypes You may have noticed that almost every interface and type in `@pothos/core` take a generic that looks like: `Types extends SchemaTypes`. This type is what allows Pothos and its plugins to share type information across the entire schema, and to incorporate user defined types into that system. These SchemaTypes are a combination of default types merged with the Types provided in the Generic parameter of the SchemaBuilder constructor, and includes a wide variety of useful types: - Types for all the scalars - Types for backing models used by objects and interfaces when referenced via strings - The type used for the context and root objects - Settings for default nullability of fields - Any user defined types specific to plugins \(more info below\) There are many ways these types can be used, but one of the most common is to access the type for the context object, so that you can correctly type a callback function for your plugin that accepts the context object. ```typescript export interface SchemaBuilderOptions { exampleSetupFn?: (context: Types['Context']) => ExamplePluginSetupConfig; } ``` ### Using user defined types As mentioned above, your plugin can also contribute its own user definable types to the SchemaTypes interface. You can see examples of this in the several of the plugins including the directives and `scope-auth` plugins. Adding your own types to SchemaTypes requires extending 2 interfaces: The `UserSchemaTypes` which describes the type the user will need to provide, and the `ExtendDefaultTypes` interface, which is used to set default values if the User does not provide their own types. ```typescript export interface UserSchemaTypes { NewExampleTypes: Record; } export interface ExtendDefaultTypes> { NewExampleTypes: PartialTypes['NewExampleTypes'] & {}; } ``` The User provided type can then be accessed using `Types['NewExampleTypes']` in any interface or type that receives `SchemaTypes` as a generic argument. ### Request data Plugins that wrap resolvers may need to store some data that is unique to the current request. In these cases your plugin can define a `createRequestData` method, and use the `requestData` method to get the data for the current request. playground-examples/architecture-writing-plugin/plugin.ts#plugin The shape of requestData can be defined via the second generic parameter of the `BasePlugin` class. The `requestData` method expects the context object as its only argument, which is used to uniquely identify the current request. ### Wrapping arguments and inputs The plugin API does not directly wrap individual input fields. `wrapResolve` and `wrapSubscribe` can transform the `args` object before passing it to the original function. These wrappers receive arguments after any registered argument mappers have run; use `fieldConfig.argMappers` when the transformation needs to happen before resolver or subscription wrappers. Figuring out how to wrap inputs can be a little complex, especially when dealing with recursive inputs, and optimizing to wrap as little as possible. To help with this, Pothos has a couple of utility functions that can make this easier: - `mapInputFields`: Used to select affected input fields and extract some configuration - `createInputValueMapper`: Creates a mapping function that uses the result of `mapInputFields` to map inputs in an args object to new values. The relay plugin uses these methods to decode `globalID` inputs. This example uses the same utilities to trim marked strings, including strings inside a nested input list. Fields without the `trimInput` extension retain their whitespace: playground-examples/architecture-plugin-inputs/plugin.ts#mapping Using these utilities allows moving more logic to build time (figuring out which fields need mapping) so that the runtime overhead is as small as possible. `createInputValueMapper` may be useful for some use cases, for some plugins it may be better to create a custom mapping function, but still use the result of `mapInputFields`. `mapInputFields` returns a map whose keys are field/argument names, and whose values are objects with the following shape: ```typescript interface InputFieldMapping { kind: 'Enum' | 'Scalar' | 'InputObject'; isList: boolean; listDepth: number; config: PothosInputFieldConfig; value: T | null; // null is possible for an InputObject with mapped descendants. } ``` if the `kind` is `InputObject` then the mapping object will also have a fields property with an object of the following shape: ```typescript interface InputTypeFieldsMapping { configs: Record>; map: Map> | null; } ``` Both the root map and nested `fields.map` maps contain fields with non-null mappings and input objects with mapped descendants. If the mapping function returned null for all fields, the `mapInputFields` will return null instead of returning a map to indicate no wrapping should occur ### Argument mapping and errors Register an argument mapper in `onOutputFieldConfig` by returning a config with an updated `argMappers` array. Each mapper receives `(args, context, info)` and returns the next argument object, or a promise of it. `args` is a `Record`; `info` is Pothos's `PartialResolveInfo`. Preserve existing mappers when appending your own. Mappers run sequentially in array order, awaiting each result before passing it to the next mapper. For a resolver call, execution enters these layers in order: 1. `wrapArgMappers` wrappers, which see the arguments before mapping. 2. The field's `argMappers`. 3. `wrapResolve` wrappers, which see the mapped arguments. 4. The application's resolver. Subscription setup follows the same order with `wrapSubscribe` and the application's subscribe function in the last two positions. The subscription's event resolver has its own resolver path; do not assume mapping runs only once per subscription. Within each wrapper hook, the first plugin in the builder's `plugins` array is outermost. Configuration hooks run from the last plugin to the first, so appending in `onOutputFieldConfig` determines the final mapper-array order at build time. A `try/catch` inside `wrapResolve` cannot catch a mapper failure: mapping happens before that wrapper is entered. Use `wrapArgMappers` for an outer error boundary. The example below appends a synchronous normalizer and an asynchronous validator for fields marked with `extensions: { normalizeName: true }`. The boundary converts their `NameInputError` failures to a GraphQL error with a `BAD_USER_INPUT` code. playground-examples/architecture-arg-mappers/plugin.ts The `await` inside `try` catches both a synchronous throw and an asynchronous rejection. Returning the promise without awaiting it would let its rejection escape that `catch`. Preserve an absent function by returning `undefined` unchanged: this hook is also called when a field has no subscribe function. It should not accidentally manufacture one. The boundary also encloses resolver/subscriber wrappers and the application function, so it can receive their errors too. Handle only errors belonging to the policy you intend to implement; this example rethrows every error other than `NameInputError`. It does not catch GraphQL document validation or variable-coercion errors, which occur before field execution, or errors thrown by a subscription's async iterable while producing events. Use the registered plugin and opt in on the field in a separate `schema.ts`: playground-examples/architecture-arg-mappers/schema.ts `greeting(name: " Gina ")` returns `"Hello, Gina!"`. A blank name throws synchronously; `"reserved"` rejects from the asynchronous mapper, even when surrounded by whitespace. Both failures prevent the resolver from running. `"broken"` reaches the resolver and retains the `"Greeting unavailable"` error without a `BAD_USER_INPUT` code. These mappers preserve the schema's string argument shape. Registering a mapper does not itself change the TypeScript argument types inferred from field definitions. The earlier trim example remains a valid `wrapResolve` transformation; moving its mapper into `argMappers` would make it run before all resolver wrappers instead of inside that plugin's wrapper. ### Removing fields and enum values Plugins can remove fields from objects, interfaces, and input objects, and remove specific values from enums. To do this, simply return null from the corresponding on\*Config plugin hook: playground-examples/architecture-plugin-hooks/plugin.ts#field-options playground-examples/architecture-plugin-hooks/plugin.ts#remove-input-enum Introspection omits the `removeMe` output and input fields and the enum value backed by `removeMe`. The other fields and enum values remain. Removing whole types from the schema needs to be done by transforming the schema during the `afterBuild` hook. See the `sub-graph` plugin for a more complete example of removing types. ## Useful methods: - `builder.configStore.onTypeConfig`: Takes a type ref and a callback, and will invoke the callback with the config for the referenced type once available. - `fieldRef.onFirstUse` Takes a callback to invoke once the config for the field is available. - `buildCache.getTypeConfig` Gets the config for a given type after it has been passed through any modifications applied by plugins.