Groking redwood

Get Help and Help Others
1

I’m bringing this discussion in here from the Redwood discord chat
https://discord.com/channels/679514959968993311/679514959968993476/722929825962131526

Tobbe Yesterday at 11:45 PM

The thing that’s been slowing me down the most getting things up and running with Redwood has been my lack of understanding of the API/DB parts. Coming in to this I had only heard of GQL a few times, but never seen it before and certainly never used it for anything. Also had no idea what Apollo was, or what it was used for, or Prisma. It was all just a bunch of words/terms with no meaning. I struggled with figuring out how they all fit in to the Redwood puzzle. What did what? What was it used for? One thing that I think would have helped me was if the technologies involved were added to the image I’m attaching here. Like "this part is using React, this is Apollo client, this is Apollo server, here’s Prisma. This communication is done using gql, this is sql, etc. I use React all day, every day, so the new concepts introduced by Redwood in that part I picked up on in minutes. I’ve also written lambda functions with several providers before, so that’s easy to grok. But I’ve only ever written them all from scratch, mostly replying with simple a simple JSON data object on a few http GETs.

@dom You’ve been doing a lot of awesome updates to the docs lately, you want to make a stab at improving/expanding the apollo/prisma/gql parts of the docs/tutorial? @rob I guess you’re the original author of all this, yeah? Did you also create the image posted? Do you think it would work adding in the tech used too, or would it clutter it too much?

image
image1212×326 23.8 KB

dom Today at 1:01 AM

@Tobbe Totally. I understand where you’re coming from. And to be honest, I still don’t know that much about Apollo or Prisma. But I do know where they fit into the stack.

I’m hesitant to change the tutorial too much. By the time we hit 1.0, the tutorial’s probably going to double, if not triple, in length.

I wouldn’t mind writing some kind of primer, “Apollo/Prisma for Redwood Developers”, since they’re core technologies. In general, I think we do need a lot more explanatory content.

I like the idea of making a copy of that figure with labels of all the technologies involved.

Another consideration, though, is sides and targets.

Right now Redwood only has two sides, web and api, each with a fixed target, browsers and nodejs lambdas respectively. But Redwood’s architecture is designed for more.(edited)

So if we start documenting everything we use, it’ll only get multiplicatively (probably not a word) harder to keep doing so.

That’s not to say we shouldn’t include as much explanation as we can, but just at the right level of detail. And I think the point you made is where we need it most–just how does it all fit together?

thedavid Today at 6:46 AM

@Tobbe @dom We’ve talked about this internally as well. And, personally, I currently see the number one challenge to adopting Redwood being the learning curve for the API. To be clear, it’s well designed. But GraphQL + Functions + Prisma is complex no matter how you slice it. I think there’s going to be a lot of value to Cookbooks and Tutorials focused on understanding how to do GraphQL and Prisma (DB Schema + CRUD) the Redwood Way™ In the meantime, could you take this conversation over to the Forums and just start listing the questions you have? The hangups you’ve had? What you originally thought things were doing but had “Ah Ha!” moments about? That kind of insight would be pure gold for us.

@Tobbe one thing that I’ve found helps people is to explain that the db in the service files is the Prisma Client object from api/src/lib/db.js and the docs are here:

Was this clear to you already? Or is this a helpful “Ah ha!”

Tobbe Today at 8:03 AM

Yeah, that was clear already. It clicked for me a few days ago when I got a mental model of all the parts involved. I’ll write something on the forums

That was all that was written in the chat about it. I’ll continue the discussion in a reply to this topic (possibly later today)

2 Likes
2

Yeah I mean we specifically state at the start of the tutorial that you should be familiar with React and GraphQL (maybe we could add Prisma to that list?) because it’s not reasonable to explain all of these concepts in depth, for time’s sake, to someone before even starting the tutorial. I also think you can make it through the tutorial without knowing GraphQL and Prisma, but you may be hard pressed to branch off on your own afterwords and start writing your own app.

I’d be careful adding too much theory directly into the tutorial as we have a mission to introduce all the core features of the framework, not turn it into a lecture. We (Tom and I) felt that the Side Quest: How Redwood Works with Data section was a good spot for an interlude and is hopefully just enough theory to help those that are curious about where this data is coming from and where it’s going. Although looking through it now I see it only mentions Prisma once, in the little sidebar about the db variable. I’m all for clarifying that data flow in this section.

In regards to the diagram, I’d probably make a new one that’s more technology/concept focused (React -> Apollo Client -> Apollo Server -> Prisma -> Database) this one is more literally-focused (is that a think?) that shows how the data moves between the physical files you see in your editor to get your data to you. I think just adding more labels to this one will clutter it too much.

We could also link to specific pages in the Wrapping Up section of the tutorial for users who are ready to take the next step and include links to Apollo and Prisma docs, and link to specific docs depending on your familiarity with various concepts (never used GraphQL before, just need an overview of writing mutations, etc.)

If someone wanted to take on the task of adding our own custom docs that explain Apollo/GraphQL and Prisma from scratch, but in a Redwood-focused way, that’d be awesome! But that’s a loooottttt of work and those projects are going to be better at maintaining their own docs than we will ever be. The Apollo docs in particular are excellent at explaining GraphQL already. Although they don’t know about some of the tricks we’re using, like auto-mapping of the resolvers.

3

100% agree.

I recently set up my first Gatsby site, and doing so I went through their tutorial. It’s very thorough, even going so far as helping you install node, git, going through code editors, etc. But even they thought it would be too much to explain/teach GraphQL, so they link out to an external tutorial about that

NOTE: Gatsby’s data layer is powered by GraphQL. For an in-depth tutorial on GraphQL, we recommend How to GraphQL.

– Part 4: Query for Data with GraphQL | Gatsby

Yes you can. I did :slight_smile:

Yes, a lot of Googling requried…

I love this part of the tutorial, I referenced back to it several times. Very good :+1:
And yes, it does reference both Apollo and Prisma, but even so I first didn’t understand what was used for what. I think a visual diagram would have been helpful to me.

Yes! This would have been perfect. And I agree about the labels, that’s what I’m afraid would happen too.

I think links at the start of the tutorial, and at the end of the tutorial would both be helpful

Before tutorial:
“Make sure you’re familiar with these things before starting”

  • link 1
  • link 2

and

After tutorial:
“Read this if you want to know even more and dig deeper”

  • link 1
  • link 2

I just found their SpaceX tutorial earlier today and have started working though it. It does look very good so far!

I think Redwood is in a bit of a unique situation in that it does so much! So naturally there are a lot of things to explain. We can’t possibly include full tutorials for React, Apollo, Prisma, Netlify Functions, TailwindCSS (or whatever styling thing to use) etc.

2 Likes
4

Just to be super clear, this kind of diagram is what I think would have helped me

rw_overview_diagram
rw_overview_diagram1304×516 62.9 KB

As you can probably tell from my Paint skillz I’m not your guy to actually make said diagram… :laughing:

5 Likes
5

@Tobbe This is a really great blog post that helped me grok GraphQL and caching according to Apollo.

1 Like
6

Just finished going through the Apollo tutorial. It started off great, but deteriorated a bit towards the end. Still super helpful for my understanding of gql/apollo though :+1:

Made me want to write my own version of that tutorial, but targeting Redwood :smiley: Too bad I have a job to do as well that’s taking all my time :stuck_out_tongue:

1 Like
7

Not sure I’d be hitting any relevant part of the mark here but…
I’m pretty new to all of it and Typescript was a ah-ha! moment to me, most specifically on the api side.
The one thing that really, really tied a lot together was seeing this part of the doc:

I could finally use the generated types of my schema directly in my code, which makes navigation through it a lot easier and helps seeing how things work between the schema, the sdls and the services. I feel mostly in charge of my wild api thanks to it x), but I admit, it’s a lot to take on.

2 Likes
8

Ok, this is all really good discussion and speaks to what I think is a priority theme emerging from new Redwood developers → Something akin to:

“…you talk about the Redwood API, but where does Redwood end and Prisma, or Postgres, or Apollo GraphQL, or Lambda Functions, or Services, or … begin?”

For individuals new to Redwood (i.e. most all of us :wink:) it’s no trivial task just to round up which documentation goes with which components.

Potential Next Step: Virtual Meetup

I’m blocking off Thursday, July 9th from 10:30-12:00pm Pacific to figure out how to use https://hopin.to/ (expo/booth feature) to host an informal community conversation about these topics. The topic will be the Redwood API. The goal will be two-fold:

  1. identify common API questions and pain points for developers “getting started” with Redwood
  2. through informal walkthroughs and brief, lightweight presentations, identify which explanations and resources are most helpful

We can use this discussion (and others) to source some topics for a fluid agenda. And anyone who’d like some time to present or ask questions could be scheduled as well. But overall, the Hopin service will allow people to drop in and out of the main conversation while everyone can watch and participate by chat.

  • Count me in (that date/time works)
  • Count me in (but different date/time)
  • Interesting but not of value to me specifically
  • Meh, I don’t see the value/need
0 voters
9

10:30 am PST is 5:30 pm GMT/UTC and 19:30 CET
Hope I got that right, timezones are a pain :clock1030:

1 Like
10

@Tobbe Prisma’s Data Guide is available as of today:

11

@dom @Tobbe @Terris @tctrautman

Ok, we’re one for a Meetup/Discussion tomorrow! We’re going to give this a go over the course of an hour with a small group. (The date/time displayed below should be localized to you.)

2020-07-09T17:30:00Z → 2020-07-09T18:30:00Z

After Dom and I tested out the software, we’re going to borrow from Prisma and flag this as --experimental. There are definitely some UX issues to work out if we’re attempting to run this through the Hopin event software.

And, to be clear, even though this is a trial run your participation is needed and valuable :100:!!

Here’s the plan:

  • we’re limiting this to 5 people. Each of you has first dibs on a “ticket” to join. If you are still available, DM me for a link to get access.
    • Anyone who’s interested is welcome to DM me. I’ll sort invites based on “first come” basis.
  • Step 1: we need to understand your experience joining the discussion using Hopin. So I won’t give specific instructions. BUT we’ll be on Discord for a backchannel to help each other out in case of problems.
  • Step 2: once we’re all in the virtual Meetup, we’ll debrief the experience and try out some functionality (chat, drop-in to live video, screen share, etc.)
  • Step 3: we’ll dive into some topics about Redwood API and current state of the union. Together, we’ll put together a plan for a larger, public group Meetup we’ll schedule for later next week.

Make sense and sound like a plan?

Hope to see you tomorrow. :crossed_fingers:

3 Likes
12

@thedavid I’m looking forward to this! FYI I just tried sending you a DM to get the link and received an error saying that you weren’t receiving messages right now. I think there might be some Discourse settings that need tweaking.

13

Ah, sorry about that! Sending you the link now by DM. Excited you’re able to join.

1 Like
14

Would love a quick recap of the meetup if anything interesting was said :slight_smile: Super sad I couldn’t make it today :frowning:

15

Partly testing the system and then making some plans for a full go next week. I’ll post some potential topics for discussion.

More to come!

2 Likes
16

All right, Meetup event registration for this Friday is live!

https://community.redwoodjs.com/t/our-first-public-virtual-meetup-is-this-friday-join-us/910/2

3 Likes
17

@Terris @tctrautman

Wanted to see if either of you were interested in kicking off specific topics or questions during tomorrow’s public Meetup? The idea would be to share (over the course of several minutes) some questions you have related to the Redwood API or an “ah-ha!” momentum you had. You don’t need to be an expert. But, rather, kick start a discussion about a topic.

No pressure, but let me know if you’re interested and I’ll put you on my list.

Lastly, tomorrow’s going to be a bit of an experiment. So no promises on my end about how things are going to go. We’ll have fun regardless :wink:

18

I think I can come up with a few questions :wink:

1 Like
19

Perfect! We’ll see how it goes. No need to prepare anything other than a question or two. If we seem to be at a lull and need to kick start conversation, I might use that as an opportunity to have you initiate a conversation (with my help). Sound like a plan?

20

@thedavid I also have a question that might be a good topic for group discussion for if conversation slows down.

Also, I’m not sure this fits in the “ah-ha!” moments bucket… and I’m sure this is incomplete or perhaps even misleading in some places, but I put this together after our conversation last week with the thought that it might be helpful for new folks coming into the community who aren’t familiar with the boundaries between the tools and Redwood concepts:

rw-layers
rw-layers1206×758 72.7 KB

8 Likes