Best practices for organizing queries

[villesau]

I found good best practices about folder structure: https://nexusjs.org/docs/guides/best-practices#consistent-file-structure-for-graphql-type-imports

However it does not cover a case where query might return multiple types. What would be the best practice to organize such queries?

[ericyd]

We quickly found ourselves struggling with file organization as well when we started using Nexus. The structure we've been using is based on this model

src/graphql
| - Domain (e.g. User, Post, etc)
|    | - index.ts (exports everything else from this Domain)
|    | - mutations
|    |    | - specific-thing.ts (e.g. create-user.ts)
|    |    | - specific-thing.spec.ts (e.g. create-user.spec.ts)
|    | - queries
|    |    | - specific-thing.ts (e.g. user.ts)
|    |    | - specific-thing.spec.ts (e.g. user.spec.ts)
|    | - types
|    |    | - specific-thing.ts (e.g. user.ts)
|    | - util
|    |    | - utility-function-one.ts
| - types*
|    | - specific-type.ts (e.g. validation-errors.ts)

*miscellaneous top-level types that don't fit in exactly 1 domain, such as a Credit Report. These may not have their own Domain if there aren't specific queries or mutations associated with them, but the types still need to be defined in the API

There are times when things don't cleanly fit into one of these categories but for the most part it has served us well. No idea if people from the Nexus team would agree with this structure, this is purely a demonstration of how we've structured our project

[villesau]

Nice, thanks! Looks like a solid yet simple structure 👍 I assume that the domain here is the main type such as User?

Do you have any cross-domain concerns? Like, let's say FB feed: It can have regular posts (like Post), group posts (GroupPost) & events (Event). where would you place the home feed query in that case? Or would you consider it as it's own domain altogether, such as HomeFeed?

[ericyd]

Yes we equate domain to a top-level concept like User

We actually have a Feed in our app too and we just have a separate Domain for Feed. It has a single query feed and many types. feed query returns a Connection and each type is a union of all the possible types that can be returned in the Feed. Some of the types in the "FeedItem" union do not live exclusively in the Feed domain. For example, we expose monetary transactions in our feed, but Transaction has its own domain where that type lives.

I don't propose that this is the all-time-best organization, just sharing our experiences. I think there's always going to be some "aggregate" types of queries like this, and there are probably multiple reasonable ways to approach it. Another alternative I'm thinking of is to have a general directory for cross-domain queries/mutations, perhaps something like

src
| - User
| - Transaction
| - Post
| - common
|    | - feed query
|    | - feed item

[villesau]

I think it makes sense. We also treat our Feed as it's own domain, although it solely relies on other objects and also have just single query. Our usage of Nexus is just growing to the point where we might want to further split files to queries, mutation and types like you've done.

Thanks for sharing your experiences! Very helpful to see how others think about organizing Nexus stuff.