Pothos v4 is now available! 🎉Check out the full migration guide here



The 2.0 release was mostly focused around re-designing the plugin system so it could be properly documented, and made available for broader adoption. The previous plugin system allowed plugins to use the FieldWrapper base class to wrap fields. Unfortunately the overhead of this wrapping strategy was significantly higher than expected, and could not be optimized in a way that justified the conveniences it provided.

Breaking changes

Auth plugin

The auth plugin has been replaced by a new scope-auth plugin. Unfortunately due to the performance problems with the original field wrapping API, the auth plugin had to be re-designed, and maintaining the existing API at the cost of significant performance overhead did not seem justified.

Any existing usage of the auth plugin will need to be replaced with the new scope-auth plugin. The API of the new scope-auth plugin is substantially different, and the specifics of the migration will depend on the exact usage of the original auth plugin. Documentation on the new plugin can be found here.

Plugin names

Plugin names have been normalized, and are now exported as the default export of the plugin packages.


// old
import '@pothos/plugin-simple-objects';
const builder = new SchemaBuilder({
  plugins: ['PothosSimpleObjects'],
// new
import SimpleObjectsPlugin from '@pothos/plugin-simple-objects';
const builder = new SchemaBuilder({
  plugins: [SimpleObjectsPlugin],

Plugin Order

The old plugin API did not make strong guarantees about the order in which plugin hooks would be executed. Plugins are now always triggered in reverse order. The most critical plugins (like auth-scope) should appear first in the list of plugins. This ensures that any modifications made by other plugins are applied first, and lets the more important plugins be at the top of the call stack when resolving fields.

InputFieldBuilder.bool and InputFieldBuilder.boolList

The bool alias on InputFieldBuilder has been removed, as it was inconsistent with the other field builders and general naming convention of other methods. Usage of this method should be converted to the canonical boolean and booleanList methods.


// Old
// New

args on "exposed" fields

Fields defined with the expose helpers no longer accept args since they also do not have a resolver.

Plugin API

The Plugin API has been completely re-designed and is now documented here. new instances of plugins are now instantiated each time toSchema is called on the SchemaBuilder, rather than being tied to the lifetime of the SchemaBuilder itself.

New features

  • Lots of new documentation
  • New scope-auth plugin
  • New directives plugin
  • New plugin API
  • Significant performance improvements in smart-subscriptions and scope-auth plugins

On this page