Define Principals

[jasonkuhrt]

Defining principals for pumpkins will help clarify for us how to make optimal tradeoffs. It will also give users better transparency into if the tool aligns with their needs/wants, and what they can expect out of the project mid/long-term.

During our brainstorming we sketched various sounds-good-maybe-maybe-not principals.

This issue is to take the next pass(es) distilling toward the essence.

I think we should limit ourselves on the principals we take on. Three? The goal is to simplify as much as we can tradeoff flashpoints, reduce the number of things we should be aiming to satisfy. In some ways more principals means owning more complexity, e.g. something akin to this:

Show Big Image

We can treat the following as a living document. As we discuss and revise, we can re-edit the following to stay up to date.

---

Principals

1. Its just an API

As much as possible users should be working with code. Activities like fiddling with the file system, navigating docs, writing deploy scripts, checking terminals, and more is energy lost. Our job is to provide an API where the leverage of every line of code is as high as it can be for the developer. The less time users have to pend outside TypeScript files the better.

2. Declarative Code Visualized

We leverage declarative APIs for CRUD, field projection, auth, and more to produce schematic overviews of the application. By doing this we make it easier to onboard collaborators and understand your architecture. We are paying back the user for using our API, aka. we are giving them leverage.

3. Generated What?

Generated artifacts are invisible to the developer

Example Applications

1. The user does not need to manage Photon.JS
   • think about declaring Photon.JS in their PSL
   • think about what output path to use for Photon.JS
2. The user does not need to mange nexus typegen
   • think about when to turn it on or off
   • think about what path to output it to
   • incorporate its existence into your mental model (it is sufficient to understand we provide TypeScript type reflection on steroids)
   • think about if it should be a declaration file (.d.ts) or just regular TypeScript file (.ts)
   • think about how it should be imported into your project (@types, import ... from ..., ...)

Other Detail

We have a significant amount of user non-success with the nexus and nexus-prisma workflow. We want our framework to allow users to never have to think about:

1. That there are generated artifacts
2. That there are generated artifacts in nexus-prisma that depend on generated artifacts from prisma
3. That the nexus generated artifacts are produced by the same app which uses them to get typechecked, and that failure in the latter never blocks from building/updating the former (otherwise chicken/egg).
4. Doing special things for deploying to Heroku, zeit, and so on.

We are aggregating user DX frustration about this issue here.

4. Zero Config

...

5. Smart Sherpa Not Static Guides

Instead of static guides that require the user to build a delta from their current position to we should move guides to the front lines. Think $ <thing> doctor on steroids.

$ <thing> what do I do next?

• "it looks like you aren't setup for deployment ..."
• "it looks like you haven't set up any graphql types yet ... "
• "it looks like you haven't setup your PSL yet ... "
• "it looks like you you haven't mapped X object at all ... "

5. Cake Before Cup Cakes

We start with ideal developer experiences. We avoid premature modularization. When in doubt, we do not modularize. We value finding natural wholistic seams over time.

6. Top Down Idealized Design

We envision our ideal developer experience and then work backwards to where we are.

7. We Expose It We Own It

Anything we expose our users to (cli commands, config, api exports, ...) we take responsibility for owning the mental model and approachability for. We are not a disjointed bag of features that users piece together a mental model for themselves by traversing half a dozen different docs. If we re-export nexus core building blocks but the docs for those building blocks are poor or cumbersome to access from our framework docs then we take it upon ourselves to resolve that (be it upstream contributions, creating our own docs, etc.).

8. Never Leave Your Development Flow

...

[jasonkuhrt]

ramps, not stairs.

[jasonkuhrt]

@Weakky I think we can close this as we have the seven goals of Nexus now https://nexusjs.org/#the-goals-of-nexus