File layout
Pothos tries not to be opinionated about how you structure your code, and provides multiple ways of doing many things. This short guide covers a few conventions I use, as a starting place for anyone who is just looking for a decent setup that should just work. Everything suggested here is just a recommendation and is completely optional.
Files
Here are a few files I create in almost every Pothos schema I have built:
-
src/server.ts: Setup and run your server (This might be graphql-yoga or @apollo/server) -
src/builder.ts: Setup for your schema builder. Does not contain any definitions for types in your schema -
src/schema.tsorsrc/schema/index.ts: Imports all the files that define part of your schema, but does not define types itself. Exportsbuilder.toSchema() -
src/types.ts: Define shared types used across your schema including a type for your context object. This should be imported when creating your builder, and may be used by many other files. -
src/schema/*.ts: Actual definitions for your schema types.
Imports
Import types directly from the files that define them rather than importing from another file like
index.ts that re-exports them. index.ts files can still be useful for loading all files in a
directory, but they should generally NOT export any values.
Plugins
Which plugins you use is completely up to you. For my own projects, I will use the simple-objects,
scope-auth, and mocks plugins in every project, and some of the other plugins as needed.
mocks and scope-auth are fairly self explanatory. The simple-objects plugin can make building
out a graph much quicker, because you don't have to have explicit types or models for every object
in your graph. I frequently find that I just want to add an object of a specific shape, and then let
the parent field figure out how to return an object of the right shape.
Backing models
Pothos gives you a lot of control over how you define the types that your schema and resolvers use,
which can make figuring out the right approach confusing at first. In my projects, I try to avoid
using the SchemaTypes approach for defining backing models. Instead, I tend to use model classes
for defining most of the important objects in my graph, and fall back to using either the
simple-objects plugin or builder.objectRef<Shape>(name).implement({...}) when it does not make
sense to define a class for my data.
Co-locating queries
In bigger graphs, having all your queries/entry points defined in one place can become hard to
manage. Instead, I prefer to define queries alongside the types they return. For example, queries
for a User type would be defined in the same file that contains the definition for the User
type, rather than in a central queries.ts file (using builder.queryField).