_The_ Nexus tutorial

[jasonkuhrt]

What

• Create a richer tutorial than what we have today
• Something that introduces concepts along the way.
• References
  • https://redwoodjs.com/tutorial/welcome-to-redwood
  • https://nextjs.org/learn/basics/create-nextjs-app

Why

• We need a stronger funnel for onboarding users than we do today
• We don't have confidence to dump e.g. 1000 users onto nexus website right now––there is a strong amount of self-direction needed still

How

• New repo graphql-nexus/tutorial that contains the final working code
• Tutorial content inside graphql-nexus/nexus docs
  • Would replace current tutorial content
• Ecom domain
• Using Prisma plugin
  • But avoid t.model and .crud because currently limited
• Deploy to Heroku because plays to our current serverful strengths
• Integrate authentication and authorization

[jasonkuhrt]

Sketch with @Weakky today:

Content "formula"

# Let's Do X Goal

## We'll Need Y feature

### Aside about Z concept

... 

repeat

• just a rule of thumb
• sometimes a concept doesn't need to be explored much, just referred to other docs
• sometimes a concept can be explored inline
• sometimes a concept can be explored as a standalone page

Content skeleton

1. Installation & Starting development
   • Notes:
     • Mention nexus create app
     • Work from scratch to learn raw basics
     • npm
     • let Nexus scaffold the TypeScript config
   • New Concepts:
     • Nexus Package
     • Nexus CLI
     • Nexus Dev Mode
     • TypeScript
2. Model some data in graphql User, Order, Product
   • Notes
     • All the objects created here are simple versions, subsets, of what we'll do with Prisma models
     • Model relations between the three objects
     • Add some relation args to show off 1) more of the API 2) reflection benefits
     • Talk about SDL file
   • New Concepts
     • GraphQL SDL File
     • Nexus Schema Type Definers
     • Nexus Reflection (typegen)
3. Add crud
   • Notes
     • Upgrade to db in memory object
     • is crud the wrong term?
     • in schema design, don't actually do crud style (signup, checker, ...etc.)
   • New Concepts
     • Nexus addToContext (+ Nexus Reflection pt. 2)
     • GraphQL Playground
     • GraphQL root types (entrypoints)
     • GraphQL nullable outputs by default
     • GraphQL non-nullable inputs by default
4. Add some tests
   • Notes
     • Setup jest & ts-jest
     • Call each entrypoint
     • Tests need to scaffold data fixtures
     • Use inline snapshots, mention scaling with non-inline + vscode ext/wallaby.js/etc.
     • What if we need data fixtures that don't have mutation operations
   • New Concepts
     • Nexus Testing module
     • Testing GraphQL Client
     • API Testing Strategy (Integration, client input, api output, snapshot)
     • Snapshot Testing
5. Persisting Data (w/ Prisma)
   • Notes
     • Use Postgres
     • Setup Postgres via Docker OR postgres.app (windows? linux?)
   • New Concepts:
     • Nexus Plugins
     • Prisma Client
     • Prisma CLI
     • Databases (Postgres)
     • Docker
6. Testing part 2, with Prisma
7. Authentication
   • Notes
     • GitHub or maybe Auth0?
     • nexus-plugin-jwt-auth?
   • New Concepts:
     • Nexus req <> addToContext (user.id)
     • JWT
     • Nexus Backing Types (composite Prisma Model + Identity provider)
8. Authorization
   • Notes
     • Enforce user can only update own data
     • Use the Nexus Schema Auth plugin
     • aside about future api
     • nexus-plugin-shield?
9. Testing part 3, with auth
10. Deploy
    • New Concepts
      1. Nexus build
      2. Migrating production db
11. Going further
    1. Custom Scalars
    2. Relay Connections
    3. Custom Backing Types?
    4. (Maybe?): Schema middleware (eg: resolver execution time tracing)

[gustawdaniel]

I can't wait for this tutorial. Great idea!

I have problems especially with sharing database connection with express.

Please add more about:

• express
• sharing db
• implementing subscriptions

Please look at this code:

https://stackoverflow.com/questions/62233427/nexus-dev-command-runs-app-twice-how-to-fix-this-behavior

Can I please for your review?

[jasonkuhrt]

~@gustawdaniel fyi Nexus' official discussions is at https://github.com/graphql-nexus/nexus/discussions.~

Just saw that you did.

[johnslemmer]

Just wanted to do a quick drive by and say you all are kicking butt! I've been following Prisma, and Nexus for a while now and am stoked about Prisma v2 and how Nexus is maturing as well. I just read through the Nexus tutorial that you have done so far. You are off to an awesome start. Anyway, that is it. Just a little encouragement for you all because you are doing great work!

[jasonkuhrt]

Thanks @johnslemmer! Drive by thank-yous do more than you know 😄 🙏 Very appreciated!

[tomevans18]

Couldn’t agree more with @johnslemmer. Brilliant tutorial so far. Simple and easy to follow while also teaching all the basics needed to build an app. Plus you covered the parts most people leave out like testing and db setup. Auth is the final piece of the puzzle, which I’m excited to see.

My personal opinion on auth is that it should be kept within the nexus eco system by utilising nexus-plugin-auth or similar. External options can then be added in the future but it would again be awesome to see plugins used as I think this embodies the ethos of this framework, where the developer can focus on the APIs and not the standard logic.

[SpaceK33z]

Hey, I'm following along with the tutorial on nexusjs.org, this is my first time using it. Here's some notes;

• "You may notice that there's also now a new schema.graphql" — I think I followed along with everything correctly, but it's called "api.graphql" in my project by default.
• "You'll see some feedback from your IDE that you're missing a resolve property." — the resolve property seems to be optional now so this won't happen. Made me think that I had something wrong in my setup for a while.
• return ctx.inDb.posts.filter((p) => p.published === true) — inDb should be db.

As you can see I only encountered those three small points (I skipped the testing parts however but really appreciated that was not forgotten). I loved the tutorial! Very easy to follow and it keeps a good pace! Now patiently waiting on the authentication part 😄. Authentication and some examples on how to handle permissions would be the perfect addition.

[jasonkuhrt]

@SpaceK33z Thanks for the feedback! All three issues (and a few more) have just been fixed. 🙏

[deadcoder0904]

Wow, I loved the collocation of Mutation & Query in the same file as the model.

Loved the tutorial as well & here is a little feedback:

1. In Chapter #2, so do as you see you fit → so do as you see fit

2. The same chapter, it is said below that You may notice that there’s also now a new api.graphql file at your project root. but my api.graphql file was already generated when I typed nexus dev

3. In Chapter #3, Largely though, what it will contains will be defined by your app → Largely though, what it contains will be defined by your app

4. In Chapter 3, when we write a Mutation, type is written above nullable as it should be I think.

schema.extendType({
  type: 'Mutation',
  definition(t) {
    t.field('createDraft', {
      type: 'Post',
      nullable: false,
      resolve(_root, args, ctx) {
        ctx.db.posts.push(/*...*/)
        return // ...
      },
    })
  },
})

But in Chapter 2, in Query section, it’s written below.

schema.extendType({
  type: 'Query',            // 2
  definition(t) {
    t.field('drafts', {     // 3
      nullable: false,      // 4
      type: 'Post',         // 5
      list: true,           // 6
    })
  },
})

It should be consistent. Preferably type should be above.

5. The testing part in Chapter 4 gives me the following error in the terminal:

 ● process.exit called with “1"

 at Object.fatal (node_modules/nexus/src/lib/process/index.ts:15:11)
 at Object.getUsedPlugins (node_modules/nexus/src/lib/plugin/worktime.ts:29:13)
 at Object.createTestContext (node_modules/nexus/src/testing/testing.ts:72:27)

And also in api/graphql/Post.ts I get red-squiggly lines over id saying Property 'id' does not exist on type 'never'.ts(2339), over published saying Property 'published' does not exist on type 'never'.ts(2339), over draft saying Argument of type '{ id: number; title: string; body: string; published: boolean; }' is not assignable to parameter of type 'never'.ts(2345) & again on published. And my tests never run. I can’t get the snapshot as said in the tutorial.

There’s also a comment in the code block in JavaScript // 3 which I think should be a comment in GraphQL # 3

6. In Chapter 6, I get an error: Cannot find module 'pg' & 'nanoid' & there's no instruction about installation anywhere I think.

And after installing those modules, there is another error:

tests/Post.test.ts:65:39 - error TS2339: Property 'db' does not exist on type 'NexusTestContextApp'.

So the testing part didn’t work for me at all.

Another minor issue everywhere is the little use of commas so it’s difficult to parse the sentence. You should probably use Grammarly

[jasonkuhrt]

Thanks for the feedback @deadcoder0904! Some of the instability around testing is going to be resolved by #1069, including that exit 1 error I believe. It will get even better with #308.

[RoyBkker]

Great tutorial and easy to follow! Keep up the good work guys! One small question / notice:

• When I connected my prisma postgress db, I didn't have the autocomplete anymore when writing a resolver ctx.db. For example, I was expecting Visual Studio Code to autocomplete the ctx.db into ctx.db.post . Is this correct behaviour, or am i missing something?

Again, great job! Thanks!

[fflores97]

@RoyBkker I had the same thing happen but I think it's just that VS Code cached the types for db. I closed all my Typescript files and when I reopened them the auto completions were correct. If you find a way to refresh said cache without closing tabs by all means let me know!

[darrylyoung]

@fflores97 It might be worth trying CMD + Shift + P (or the Windows equivalent) and then selecting “Restart TypeScript server” as this typically helps if this is the problem.

[Maetes]

Would be quite nice if we can implement a file upload into this example. Would agree to help. Will there be a repo to contribute to? Regarding "nexus-plugin-shield?" and "nexus-plugin-jwt-auth?": Why not throw it in but maybe with a slidly sidnote of what they replace in code. I appreciate both plugins, but it's good to know what they're replacing.

[MLaidlawScott]

Hey, just wanted to say that the tutorial so far has been amazing! I'm having an issue on the last part of testing with Prisma, and perhaps other are experiencing the same thing.

in nexus-test-environment.js await exec(./node_modules/.bin/prisma migrate up --create-db --experimental);

this line throws an exceptions of Command failed: ./node_modules/.bin/prisma migrate up --create-db --experimental '.' is not recognized as an internal or external command, operable program or batch file.

However, when I run the command in the command line it works as expected. Any suggestions? This is on Windows if that is relevant.

[BiscuiTech]

Hey, just wanted to say that the tutorial so far has been amazing! I'm having an issue on the last part of testing with Prisma, and perhaps other are experiencing the same thing.

in nexus-test-environment.js await exec(./node_modules/.bin/prisma migrate up --create-db --experimental);

this line throws an exceptions of Command failed: ./node_modules/.bin/prisma migrate up --create-db --experimental '.' is not recognized as an internal or external command, operable program or batch file.

However, when I run the command in the command line it works as expected. Any suggestions? This is on Windows if that is relevant.

I think you need to escape the line with quotes, like so: await exec("./node_modules/.bin/prisma migrate up --create-db --experimental");

[MLaidlawScott]

Hey, just wanted to say that the tutorial so far has been amazing! I'm having an issue on the last part of testing with Prisma, and perhaps other are experiencing the same thing. in nexus-test-environment.js await exec(./node_modules/.bin/prisma migrate up --create-db --experimental); this line throws an exceptions of Command failed: ./node_modules/.bin/prisma migrate up --create-db --experimental '.' is not recognized as an internal or external command, operable program or batch file. However, when I run the command in the command line it works as expected. Any suggestions? This is on Windows if that is relevant.

I think you need to escape the line with quotes, like so: await exec("./node_modules/.bin/prisma migrate up --create-db --experimental");

Hey, I'm using backticks, I didn't realise they'd been left out the comment until now!

[MLaidlawScott]

Hey, just wanted to say that the tutorial so far has been amazing! I'm having an issue on the last part of testing with Prisma, and perhaps other are experiencing the same thing.

in nexus-test-environment.js await exec(./node_modules/.bin/prisma migrate up --create-db --experimental);

this line throws an exceptions of Command failed: ./node_modules/.bin/prisma migrate up --create-db --experimental '.' is not recognized as an internal or external command, operable program or batch file.

However, when I run the command in the command line it works as expected. Any suggestions? This is on Windows if that is relevant.

I managed to solve this. I had to use

const path = require("path"); await exec( '${path.resolve(prismaBinary)} migrate up --create-db --experimental' );

Might be worth noting that I then had issues with prettier/jest and had to use snapshots instead of inline snapshots.

[trulysinclair]

Happy to say everything works for me out of the box, if you're using Yarn 2 set yarn config set nodeLinker node-modules to get things working, however, there is no Workspaces support, unfortunately.

[trulysinclair]

Also I can't wait for you take on authentication! I'm using Firebase for a simple setup but I'd like a more custom implementation like email/password

[jk21]

1. The testing part in Chapter 4 gives me the following error in the terminal:

 ● process.exit called with “1"

 at Object.fatal (node_modules/nexus/src/lib/process/index.ts:15:11)
 at Object.getUsedPlugins (node_modules/nexus/src/lib/plugin/worktime.ts:29:13)
 at Object.createTestContext (node_modules/nexus/src/testing/testing.ts:72:27)

are there any suggestions on how to fix this error? Getting it also when running the example test setup.

[cyrus-za]

Great tutorial. I also saw the will contains will typo and also ran into the issue with prettier and inline snapshots, but using external file snapshots works great. No other issues (other than a temp issue with installing prisma plugin, that I logged with a workaround here)

The tutorial is well written and I am looking forward to the auth part. I'd love to see nexus-plugin-auth0 used

[jk21]

1. The testing part in Chapter 4 gives me the following error in the terminal:

 ● process.exit called with “1"

 at Object.fatal (node_modules/nexus/src/lib/process/index.ts:15:11)
 at Object.getUsedPlugins (node_modules/nexus/src/lib/plugin/worktime.ts:29:13)
 at Object.createTestContext (node_modules/nexus/src/testing/testing.ts:72:27)

are there any suggestions on how to fix this error? Getting it also when running the example test setup.

@haysclark do you have maybe insights? As i saw you were working on testing?

[homerjam]

Deploy to Heroku because plays to our current serverful strengths

Vercel is also delicious.

[tomevans18]

Hey, I was wondering if there was any update/progress on the auth side of this tutorial? Great information so far and has really helped get things started.

[ThomasKientz]

Sadly, Nexus is dead :

https://github.com/prisma-labs/graphql-framework-experiment/issues/1432

[Maetes]

The first thing what i did when i return from acation was reading the closing announcement which i was not aware of ...second thing was shuting down the mac go to the fridge take a beer and enjoying the end of the day....

<i'm so sad/>

[ahmedosama5200]

Why did the tutorial stop ? It' really really good, we need more of it.

[cyrus-za]

Because there is nothing to create the tutorial for. Nexus Framework no longer exists. It got killed due to lack of resources and wanting to focus more on @nexus/schema (which got renamed back to nexus now)

@jasonkuhrt you should probably close this issue.

[ahmedosama5200]

@cyrus-za sorry, I just realized that this is the old nexus framework repository. I am talking about the tutorial on the nexus schema docs here