On Nexus Framework Transition

[jasonkuhrt]

For users coming to this now please see the unframework annoucement.

🚧 🚧 🚧 🚧 🚧 🚧

---

You may have heard that nexus is becoming a framework.

If you haven't, go learn about it now: graphql-nexus/nexus#373

This issue is about the detailed plans for nexus-prisma.

tl;dr

tentatively:

• repo name will become nexus-schema-plugin-prisma
• package will become nexus-schema-plugin-prisma
• issues will migrate to graphql-nexus/nexus-future under plugin/prisma label
• docs will integrate into the framework website, removed from readme here

These changes will take place within the next few weeks feedback welcome

We hope most users are able to adopt the framework, but we want to, for the foreseeable future, keep the nexus schema prisma plugin usable too.

On npm packages

Our ideal solution and what we mentioned in the original nexus transition issue was that we would have one package, with the schema and framework plugins as their own respective modules in it. Something like this:

Nexus schema users:

npm install nexus-plugin-prisma

import nexusSchemaPluginPrisma from 'nexus-plugin-prisma/schema'

Nexus framework users:

npm install nexus-plugin-prisma

The problem with this is that the dependency trees of either plugin are quite different. The framework plugin bundles a number of "worktime" deps and Prisma deps. The schema plugin bundles almost nothing, and Prisma deps are just peer deps.

These are some of our concerns:

1. Framework deps would bloat schema plugin users' workflows/projects (larger docker images, slower install times, etc.)
2. Framework deps could lead to prisma deps not being hoisted because they show up twice in the dep graph: nexus plugin (b/c framework), and user's app (b/c peer deps). We think this might create problems for real-world projects.
3. Framework users would get unactionable peer dep warnings that are not relevant to them, because it is for schema plugin users
   • solving this would mean removing the peer dep requirements, which would compromise the feedback schema plugin users should expect.

These three limitations seem unavoidable to us, as they hit the fundamental limits of packages/package-managers in Node. Either we accept those limitations or find a different approach.

The other approch is maintaining two packages. We don't think nexus-prisma is a good package name. If the framework plugin is called nexus-plugin-prisma then we're thinking of calling the schema plugin nexus-schema-plugin-prisma. To be sure this is verbose, but it is less worse than confusion, and it is in line with our goal to make schema compoponent level usage possible, while things get optimized for the framework.

Until we can be sure the limitations are acceptable we will go with the alternative approach.

As an experiment we may also make the schema plugin available under nexus-plugin-prisma/schema. If we discover this works well enough, we'll open a discussion about turning this into the official way to consume the schema level plugin.

On repos

We currently have two repos, one for the framework level one for schema level. We've discussed the benefit of how a monorepo can simplify things. However doing so will require some enhancements to our release management tool dripip. It does not support monorepos right now.

Also, if the npm packages cannot be unified anyways, then motivation for unifying the repos seems lessoned. For now we will probably just match the repo names to the npm package names. Thus this repo would be renamed nexus-schema-plugin-prisma.

On github issues

Over the past months we've seen the difficulty users have on navigating and creating issues on the right repo. Our approach with the framework has been to invest into good labels and keeping everything central. Everything being component and first-party plugin issues. That is an ongoing transition and experiment though.

Nexus framework Prisma plugin issues are tracked there. This repo still has issues but we're thinking of migrating them to the framework repo. Once done, this repo's issues would be disabled. We see three reasons to do this:

1. Focus the community and our issue linking/triaging overhead
2. Framework plugin issues are already there. It will only make things more confusing to not have the schema plugin conform.
   1. If we go monorepo a case could be made to centralize plugin issues there, but then its out of sync with the npm packages and anyways this path is blocked by missing dripip features.
3. Many of the issues in this repo are related to the t.crud and t.model abstraction. We see the future of these abstractions moving to the framework level where it is not coupled to Prisma but made more general and applicable. Once that happens the right place to talk about these issues will migrate from plugin repo to framework repo. Issues migrations are confusing. Centralizations keeps things simple here.

On Docs

Our vision for framework plugins is a wholistic and uniform experience for application developers. This means as many enforced standards as possible on how plugins are built, shipped, etc. This extends to docs. The prisma plugin docs will thus integrate into the website. This may at first be manual, and then move to a system where plugin docs are pulled from their distributed locations (with the plugin source, repo). Either way, the docs in the README here will be extracted. In automated distributed model, the docs would live in the framework plugin repo.

Conclusion

This has been a windy path for us. After a lot of circular discussions and back and forth we've settled on this direction and these tradeoffs for now. Feedback would be most welcome. If you have ideas that you think we did not think of please do share!

[ssalbdivad]

@jasonkuhrt Where do the docs that were previously in the README live now?

[jasonkuhrt]

Linked to in the first paragraph of the schema plugin docs

Refer to the framework Prisma plugin docs for API reference and concepts. What follows here are aspects that are particular to the schema plugin only.

https://www.nexusjs.org/#/plugins/prisma?id=runtime-integration

[ssalbdivad]

Ahh okay, I still don't have a good grasp of how the plugin integrates with the Nexus framework so I didn't realize that link was referring to functionality from nexus-prisma.

Where does this leave active PRs that contained significant changes to documentation? Asking for a friend

[jasonkuhrt]

@ssalbdivad For your PR we'll take care of it!

We'd like to eventually see plugin docs return to their respective repos and then have a cron job scrape them into the website. Quite a few details there to figure out first.

[ssalbdivad]

Okay I will avoid merging the README changes into my feature branch then. Thanks!

[samrith-s]

Please remove the nexus.js.org website. Everytime I search for something, that website shows up and it has such outdated docs. Or just stop robots crawling that site. The SEO for nexusjs.org is non-existent.

[jasonkuhrt]

@samrith-s Yep, another team is handling that in the weeks to come. Trust me we're all looking forward to that :)

[jasonkuhrt]

An update, after long repeated and non-trivial discussion @Weakky I and others (@janpio) eventually came to a conclusion that bundling prisma deps is the best thing we can do. We published Nexus' view on dep management here, which relates to this. A rough snapshot of the points:

• yarn resolutions is available for version control
• we'll stay up to date with prisma
• we don't have the resources to support a version range
• but there won't be many breaking changes anymore for a while with prisma 2 so, users shouldn't need to care anymore
• even where there were breaking changes all the time nexus-prisma was pinning its peer dep strictly, thus effectively bundling prisma...
• we may in the future explore users being able to install their own prisma deps and package references to nexus prisma plugin
• we don't expect to though, see it as a growth path if absolutely needed

[jasonkuhrt]

Officially done now in https://github.com/graphql-nexus/nexus-plugin-prisma/releases/tag/0.16.0!

nexus-prisma has migrated!

If you were nexus-prisma user, please do the following to remain so

Your Dependencies

npm remove nexus-prisma @prisma/client @prisma/cli
npm add nexus-plugin-prisma

Your Imports

- import { nexusPrismaPlugin } from 'nexus-prisma'
+ import { nexusSchemaPrisma } from 'nexus-plugin-prisma/schema'

Learn More

• About the Prisma plugin for Nexus framework
• About how to migrate from @nexus/schema to Neuxs

[darrylyoung]

Hi, @jasonkuhrt. Thanks for sharing.

Is there a typo in the suggested import changes? It says to remove the nexusPluginPrisma import but this import, at least from what I can see, is actually nexusPrismaPlugin. Apologies if I'm missing something but from what I can see, I was previously importing nexusPrismaPlugin from nexus-prisma, not nexusPluginPrisma.

[jasonkuhrt]

Yes there was a typo, fixed!

[Akxe]

I got the ERROR in C:/Users/akxe/Documents/Programming/rita/apps/server/src/nexus-prisma/nexus.generated.ts(12,11): TS2304: Cannot find name 'NexusPrisma'. error once I switched to nexus-plugin-prisma/schema (and removed nexus-prisma @prisma/client @prisma/cli)

[bogdancss]

@Akxe did you manage to get around that error?

[Akxe]

I got it working, yes.

[jasonkuhrt]

For users coming to this now please see the unframework annoucement