Idea: a guide for incremental adoption of pothos in a nexus/typegraphql project

[YassinEldeeb]

Hey @hayes 👋🏼, hope you're doing well.

I'm a member of The Guild, we've been using Pothos for quite some time now and we really admire it but unsurprisingly we get a lot of questions from people asking us about the same thing which is:

Can I use my Nexus/Typegraphql setup in conjunction with an incremental adoption of Pothos?

It's painful to rewrite an entire production app from one framework to another esp when they differ a lot like Typegraphql -> Pothos migration(I did a Nexus -> Pothos migration recently and it took me a whole painful month to do it). I've started investigating a number of ways we can achieve that and I've got this minimal example which is a usage of two graphql schema builders that work internally entirely different, my goal is to make that approach as agnostic as possible literally using any graphql framework in conjunction with Pothos. The idea there is that every setup defines its own types and resolvers like:
Typegraphql -> defines Recipe object type and its resolver
Pothos -> defines Person object type and its resolver

in that particular use case where the two work on their own, it's easy to just use the mergeSchemas utility from the @graphql-tools/schema package to get a single schema from both at the end before passing it to whatever gql server we're using. The issue is that the nexus/typegraphql/etc.. setup is gonna always have all of application's types and the Pothos setup is gonna always has insufficient types, an example as in here where it gets interesting is when we wanna add a new field to our People object type to reference Recipe which is in the typegraphql setup, the issue is that even that we're very sure that the Recipe object type is gonna exist when the schemas are merged but the Pothos builder isn't aware of that and throws an error because of missing object refs and refuses to build the schema. So the challenge here that I faced is making Pothos not complain about missing types because we know they’re gonna exist when we merge the schemas, so is this a limitation from the GraphQLSchema object that gets built or is it a layer that's extensible at Pothos level? because my thinking was towards adding an option for Pothos to skip erroring bc of missing object refs if that's achievable.

Even one of the core engineers for Nexus shared this thread in which he says that he was very very impressed with the approach of Pothos after playing with it and is also thinking of what we're headed for.

Wanted to share with you this process and get your thoughts on it and hear the possible ways I'm not aware of to support such a behavior/feature.

[hayes]

This is definitely something I want to support, and something I am actively working on. I've been talking with @tgriesser as well, and he is also interested in helping these kinds of migrations easier.

So the challenge here that I faced is making Pothos not complain about missing types because we know they’re gonna exist when we merge the schemas, so is this a limitation from the GraphQLSchema object that gets built or is it a layer that's extensible at Pothos level? because my thinking was towards adding an option for Pothos to skip erroring bc of missing object refs if that's achievable.

At it's core this is an issue with GraphQLSchema. Issue may not be the right term here, but fields in a GraphQLSchema don't reference type names, the reference actual instantiated types. This means that we need to build a type in order for a field to be able to reference that type as a return or argument type. We can't just make up a placeholder, because we don't know if the type is an Object, Interface or whatever.

Fortunately this is actually very easy to work around, you can just create an empty object type with no fields and Pothos should build the schema with no issues, then mergeSchemas should be able to merge the type definitions without any issues.

To make migrations easier, there are 2 things I am working on:

A new plugin for adding types from existing graphql schemas to pothos: #700

This isn't really documented yet, and only has some of the features speced out, but the goal is to let you add types defined externally to a Pothos schema. It will support adding types on at a time (and automatically pulling other types that get referenced), but should also allow you to just pull in an entire schema, or list of types from a schema to make this a less granular process for big migrations.

The other thing I am working on is an interactive migration tool that will let you pull in an existing schema, and/or resolvers and codegen pothos definitions. The goal is to produce something that can directly reference revolvers from the existing schema, so that if you pass in a schema from something like nexus, the generated code would automatically run with the existing resolvers and be fully functional.

It should also be incremental, and work with the plugin mentioned above, so you can slowly generate/pull in more types and always have a working schema as you go through the migration process.

This is still fairly early in my exploration of these ideas and there is a lot of work left to do, but would love to collaborate on making migrations easier!