A quick start guide for using Convex with Next.js

so as I mentioned yesterday I'm hosting a hackathon and it is sponsored by convex and I wanted to make a quick little tutorial video just to show you how to get started with convex it's actually super straightforward I'm going to go to their next.js quick start guide and we're going to try to follow this so I'm gonna go ahead and run this to set up the latest next.js application I'll just go ahead and do it in my current folder which is called convex in minutes all right next.js is set up now let's go ahead and run mpm install convex so we can get that as a dependency of our project and while that's also running let's go back and we're going to run MPX convex Dev when that is done all right so when you run this for the first time in a new project and it may ask you to kind of set up your convex configuration you can just go ahead and say I want to create a new project and I'm going to use the name of this directory that we're in and once you've done that you'll get access to your convex dashboard where you can see up here we have that project that we just created and we have access to see all the functions in the database and the files and the logs and other things inside of this dashboard this dashboard ends up becoming really useful when you're trying to do your development and prototyping because you can kind of go through here and just invoke things manually if you want to and I might show you some of that functionality um second thing we're going to do is let's just go ahead and run my next app all right let's go down real quick before you can get started with next.js you do have to create a convexclient provider.tsx so I'm going to go here in my app directory and let's just create one and we're going to copy all that code paste it in save it and then secondly we're going to be using this provider inside of our layout so let's go and import that at the top and then down here we're going to use that line to wrap our children okay that's all you have to do now you're set up with convex you can start interacting with queries mutations and actions so I'm going to try to keep this little overview as fast and simple as possible which means that we're not going to be building out anything crazy we're just going to do like a to-do list tracker the first thing I want to cover in convex is that you have this convex directory that gets set up when you do MPX convex Dev and inside of this directory you have the ability to Define your schemas you can create your files that have actions mutations in queries what we want to do is I want to make a new one called like to do or to Do's whatever you want to call it and you can put any type of things in here right so in our case we want the ability for the user to add in a to-do list item inside our convex database so inside of this directory I'm actually going to go to the mutations documentation and we're going to go ahead and just bring in these two Imports like so and then we want to export a function so I'll say export const read to do is equal to mutation and then we can go ahead and pass out an object that has a Handler function in it okay so this is how you can basically write data into your convex database you have to use mutation and if you go and read up about mutations you'll find out that basically everything you do inside a mutation is transactional so you can't really contact the third party API inside a mutation those would have to be done in actions okay so for a mutation it's just taking some data and store it in a database so how do you actually take in some data well there's another argument here called args that you can pass to the mutation and I'm going to go ahead and just Define what needs to come in I'm going to say this thing needs to take in some text as a property and I'll say V Dot string okay so now if you were to call this from the front end it's going to tell you that hey you need to pass it some text so now that we have this as an argument let's go ahead and set up two different Arguments for the Handler we have context which is going to have your variables needed to write things to the database and then you also have orgs which if you hover over it you'll see you have text here so pretty straightforward we're just going to say a weight we'll say context dot DB dot insert but notice that you have a bunch of other methods here you can do queries patches or places I'm going to do insert and you're going to pass as a string of whatever database that you want in our case we're going to say to do's and we're going to pass in text is equal to args.txt okay now before I dive into showing you how to integrate the front end with this I do want to mention that there's something called an internal mutation that you can also use and this is useful if you don't want the mutation to ever be accessed from the front end okay so you can actually have actions invoke other internal mutations or like you know kind of like private queries internal queries internal mutations internal actions this gives you the extra security but in our case we do want this to be accessed from the front end so we're going to make that a public mutation now let's go back to the page here and in order to get this going let's just make a form and we'll make a input and we'll make a button that says create okay now on the form we'll say on submit we're going to go ahead and take in a e and I'll say prevent default and we're going to have to basically call the mutation here at some point and for the input I'm going to go ahead and just track some State here so I'll say const text set text equals use state of empty string and then we will say value is equal to text and on change we will say e that X e.target.value make sure you Auto Import that now I'm also going to add a use client the top of this since we're using hooks here okay so now that we have a form and we submit it we should have access to the thing that these are typed in um what we also want to do is I'm going to go ahead and try to call the mutation so with convex you can actually bring that mutation if you want to like I said create to do is equal to use mutation go ahead and Auto Import that and then we're also going to import an API object and notice that this has the autocomplete for the to Do's file that you just created and the create to do method that you just created right so that's auto correcting for this file and this method and as you add more mutations and queries those will show up so let's go ahead and call this so now we have a function that we can go down here we can just call it we're going to pass it text so going back to our UI let's just go ahead and type in some stuff I think the text is white for some reason let's go ahead and fix that real quick I'll say class name I'm sorry text black there we go and I'm gonna say hello world and I'm going to click create and let's go to our convex dashboard and you'll see that now we have a table here called to do's and that has our entry okay let me show you another thing there is a show schema at the bottom and if you were to click this convex is going to generate their recommended schema that you can use for the data that you currently have right so notice that when we tried to store stuff in convex it doesn't give us autocomplete for like whatever whatever our table names okay it's kind of like up in the air so you can really improve the type safety by going over here and say schema.ts and just paste that in so now if I do double quotes here and I click to Do's notice that it shows up and we get type safety for the things that we're actually storing into that table all right so now let's try to get these to Do's displayed on the page somewhere okay so there's another Concept in convex called a query where we can go ahead and make a function called get to Do's equals to query again this is a public query if you want it to be private you do internal query this thing is going to take in a Handler like so and when you have this Handler you have access to the context here in context like we saw before has a database object you can use so I'm going to say return context dot DB dot query and then we have access to that to-do's table and then I'm going to say dot collect so that'll fetch all the data that's in our to-do's table and we can invoke this query from the front end now if you're doing this with next and react the way convex works is they communicate with websockets so when you set up this query I'll just say like to Do's is equal to use Query and I'll say api.to-do's dot get to Do's when you set up this hook this is basically connecting to convex with websockets and anytime this data changes your UI will update okay so let's go down here and notice that this is an array of to-do's which is potentially undefined I'm going to go down I'm going to go right above the form I'll say to do's questionmark.map and I'll say to do and what we want to do is we're going to return a list of to do's dot text okay we can also key off of to do dot underscore ID if you want to so inside of here let's do Flex let's say Flex column gap of four just so that we have some nice looking to Do's if we go back to our UI you'll see that that to do is actually showing up here so now as I create new to-do's that'll automatically get updated and displayed in the UI remember we didn't have to write any manual logic to update the UI because behind the scenes this is just getting notifications from a subscription on the websocket this thing will update as your data changes which I think is actually pretty cool um one thing I'll do is when we submit let's just clear the text I'll say set text is equal to empty string and now we can go ahead and just like keep typing here like that and I want to demo this Effect one more time so if we go to our dashboard let's just go ahead and delete a few of these okay I'll delete those documents go back to our UI notice that they've all been cleared out one thing I do want to talk about are actions so there's another concept if you go through the documentation there's something called an action and if you ever want to integrate with a third-party API such as like an open AI service or like a a dictionary API you have to use actions actions are a way to communicate with third-party libraries and those actions can also invoke other mutations in queries right so using that context object that you get you can do more mutations so typically the flow is you have an action the action does an API request you get some data back you're going to use that data and pass it to a mutation to store it in your convex database and then your UI will just update if you have a query that's listening for that table or for that data so some things are also worth mentioning is that convex has file storage so you can store files directly in convex if you want to um authentication they have a good walkthrough of how you can get this all set up with clerk I personally use clerk on a previous convex project a side project and I personally like how easy it was to get started with a clerk there's this idea of scheduling so you can do cron jobs and you can schedule things to run at a various point in time I've I've done the scheduling a lot inside of mutations so for example if you have an action over here that's trying to integrate with a third-party Library you can actually invoke it like I say await context dot scheduler and then I can say run after zero milliseconds and then I can actually call an action if we were to have one let's just make one real quick so this I can kind of demo that I'll say call third party API and that's good for right now just do nothing but now the idea is that if we were to import this API object we can say API dot to Do's dot call third party API and that's going to kick off the action to run immediately and we can do some logic to basically fetch from a third-party API and then that can call a mutation like I said like run a mutation and then I can actually have that data store somewhere else okay so that's kind of the flow with context and once you start getting used to it you'll realize it's actually pretty easy to start like hooking this all together and doing a bunch of um cool stuff another quick overview is that inside the dashboard they have the ability to view logs so if you do want to if you want to see like all the logs for a function you can go ahead and like filter down again when you're saving your files all of your code is getting deployed to a real running like environment on a server somewhere right so you have access to actually hit this via an HTTP request or like we saw with the react websockets this is actually connecting to a real environment okay whatever you see working on your Dev environment will work when you promote this to production yeah so that is about it I just want to give a really quick overview for anyone who's interested in just kind of learning more about this before the hackathon starts next week other than that if you have any questions be sure to join my Discord and stay tuned for when I do kick off the hackathon next Wednesday have a good day and happy coding

Channel: Web Dev Cody

Views: 8,181

Keywords: web development, programming, coding, code, learn to code, tutorial, software engineering

Id: vaQZYRSiimI

Length: 12min 18sec (738 seconds)

Published: Thu Aug 31 2023