search

prisma-labs / team

👩‍🔬👨‍🔬Past sprint demo recordings & more
1 stars 1 forks source link

Traps & Friction Points #5

Open jasonkuhrt opened 4 years ago

jasonkuhrt commented 4 years ago

We have consolidated the issues in this epic to an organized notion table. It is public.

When this issue is resolved we should be able to mark the following as resolved too:

Weakky commented 4 years ago

4th draft

Legend

Runtime typegen

Type-checking

Pagination

Nexus two phases (walk & build)

Prisma integration

General

jasonkuhrt commented 4 years ago

Draft 2

development workflow

Problems

  1. 🔵User needs to manage additional deps to accomplish this workflow (ts-node-dev, ts-node)

    💡Nexus cli $ nexus dev|build can hide them

  2. 🔵User needs to remember the right flags to use on ts-node-dev (--transpile-only, --tree-kill) and they need to understand why.

    Example: user resisting/insecure about --transpile-only

    💡Nexus cli $ nexus dev|build can hide this

  3. 🔴Generated artifacts in node_modules may get pruned

    1. it is not obvious when they will, varies between npm and yarn
    2. when they do there is no feedback for the user they were pruned
    3. when they do there is nothing that automatically re-triggers generation

    💡Facades for photon https://github.com/prisma/photonjs/issues/261
    💡Facades for nexus typegen https://github.com/prisma-labs/nexus/issues/253
    💡Nexus typegen hook for plugins so that nexus facade solution can be benefit all plugins

  4. 🔴If the user configures --types compiler option their app will no longer automatically use typegen. There will be no feedback about why typegen has stopped working. The user will need to realize that 1) typegen goes into @types and that 2) types compiler option turns that into an opt-in/whitelist.

    💡Nexus cli can use TS compiler api programmatically to inject typegen into types option. This will however not help the IDE.
    💡VSC plugin that takes the above solution into the IDE too?
    💡New cli sub-command $ nexus doctor that looks for problems such as this and tells the user how to fix them.
    💡VSC plugin that enables doctor at all times so user does not need to remember to run $ nexus doctor

  5. 🔴There are no docs on workflow patterns and what environment variables have what effects when.

    💡Add a new workflow sub-section under nexus reference docs https://github.com/prisma-labs/nexus/issues/96

  6. 🔵User has to maintain at least two terminals, one for prisma dev and one for application dev (ts-node-dev). When they have a t.model or t.crud static error that they don't expect, they need to go through each terminal to find the issue: 1) Did photon fail to build for some reason? 2) Is my app failing to build for some reason (and thus typegen)?

    💡Have nexus dev use @prisma/sdk to programatically drive prisma dev.

  7. 🔵When starting a project it is often not obvious what combination of dependencies are needed to get what one can see working in an example (e.g. prisma 2 alpha, nexus beta, nexus-prisma regular release).

Maybe Not Problems?

  1. Unable to get into a state like described here:

    🔴User can modify app code such that nexus/nexus-plugins generation cannot succeed. This is because nexus generation relies on actually running all definition blocks in the source code. Having generation blocked because the app will not run is arguably reasonable if the reason the app will not run is due to a syntax error or some runtime error unrelated to prisma. But it is not reasonable if there is a runtime error from trying to use nexus-prisma in the correct way.

  2. Actually prisma dev emitting into node_modules is triggering ts-node-dev, even when ts-node-dev is run with --ignore-watch node_modules.

    🔵User needs to manually coordinate a nexus generate following a prisma generate
    For example if user boots up prisma dev and ts-node-dev ... in two separate terminals, there is a race condition. If prisma dev is slower, user will need to trigger a reload of ts-node-dev e.g. save on any source file.

    Maybe this is because the dependency graph is being watched as per mentioned in ts-node-dev readme:

    It restarts target node process when any of required files changes (as standard node-dev)

Deployment Workflow

Problems

  1. 🔴Users must apply a specific combination of tools and configurations thereof to successfully build their app "the nexus way".

    1. Have the right env vars in place (NEXUS_CONFIG='{...}')
    2. Use ts-node
    3. Pass ts-node the right flags (--transpile-only)
    4. Pass ts-node just the entrypoint to your schema, not server
    5. Then do a normal build tsc

    Example: user not realizing they need special env var to trigger typegen on heroku deploy

    💡We can remove iv with https://github.com/prisma-labs/nexus/issues/272, a new config option to exit the process after artifact generation.
    💡Nexus cli $ nexus build can abstract all other steps

  2. 🔴Many deployment platforms impose idiosyncratic mechanisms for how users need to structure their application. Often this structuring is not at the code level but project layout level or build pipeline. Because Prisma and Nexus use code generation techniques, users of these tools often fall victum to deployment platforms not expecting this novel-ish workflow. While we could say its not our problem, the bottom line is users experience pain, and theym ay well blame that pain on the technique of generation rather than the deployment tools.

    1. Heroku users must tap into npm run build script
    2. Zeit users must tap into npm run now-build script
    3. ... netlify, lambda ...

    lambda example: https://github.com/prisma-labs/nexus/issues/278

    💡An example for each platform
    💡For AWS Lambda, a serverless framework plugin
    💡For zeit, a custom builder wrapping the nodejs one

Other

Problems

  1. 🔵 In all of the above, because it all relies on integration of tools, the workflow that is being put together is not encoded, but rather implicit. That means error messages are never going to be in the domain of the workflow, but siloed and generic to the various tools.

    Another example, again during build, if something goes wrong during the typegen attempt, they will just see a big general ts-node or something error, probably a stack trace, etc. It would be nice if they could see a clear message "Error while building Nexus app. Failied on typegen step. Here was the error: ...".

    💡Nexus cli $ nexus build|dev can encode the workflow between tools, introduce domain error messages.

  2. 🔵NODE_ENV has effect on "develop mode" even after build. This can lead to unexpected errors. For example a user thought that there was a bug because require.resolve used on a ts file for makeSchema({ contextType }) config would lead to a path to a JS file after build. In turn this would lead to an error in typegen which asserts the file path must be to a .ts extenson file. Actually what happened was the user was running e.g. node dist/index with not NODE_ENV=production. These integration effects are unpredictable to most users and even if they don't always represent a valid combination of states users generally cannot be expected to know every permutation of this. It should just be impossible for them to get into these states in the first place.

    https://github.com/prisma/prisma-examples/pull/867#issuecomment-545400592

    💡Nexus cli $ nexus build can inject special code that disables dev features. This would only help TS users since presumably JS users do not need $ nexus build.

jasonkuhrt commented 4 years ago

@Weakky

🔵 Forgetting to run Server (thus generating new typings) prisma-labs/nexus#77 (comment) 💡Have a separate process always generating typegen

What does that solution mean/how could it help exactly?

🔵 No type-checking after cloning a repo 💡 Use postInstall npm hook to run nexus typegen

The best we could do with that solution is for it to be a pattern we suggest right? Since it would be app-level.

Cons: Less composable. We already have composability issues with t.field

We could allow the object version too, thus being backwards compatible. And that is nicer for machine use-cases as we identified the other night with t.field.

🔴 Runtime error prevents typegen from being re-run, thus making the typechecking desync/broken

How could this be fixed, though?

Weakky commented 4 years ago

What does that solution mean/how could it help exactly?

We could, for instance, have a VSC plugin running the typegen in the background, so that it's independent of the runtime.

The best we could do with that solution is for it to be a pattern we suggest right? Since it would be app-level.

Yes. "Encoding" that pattern in all examples + documenting it might be the best solution here

We could allow the object version too, thus being backward compatible. And that is nicer for machine use-cases as we identified the other night with t.field.

Still wondering whether it's a good idea to have two APIs to achieve the same thing. Might be confusing for users

How could this be fixed, though?

I don't think we can, hence why I labeled it as 🔴 (Trap)

jasonkuhrt commented 4 years ago

More since here https://github.com/prisma-labs/nexus-prisma/issues/523

ujwal-setlur commented 4 years ago

Would love a VSC plugin to generate types