So in this tutorial, I'm going to take a bit of a different approach as opposed to my other tutorials and I'm going to be starting each of my chapters with a whiteboard summary of what our goal is for the certain chapter. For example, this is chapter 1, the setup. In this chapter, our goal is to configure the environment, which means choose a runtime, choose a package manager, establish some basic BUN commands, and create the basic Next.js project and wrap it up with some useful VS Code extensions. I got a lot of feedback from all of you that sometimes it's not exactly clear what or why we are doing something in my chapters, so I hope that this kind of approach will make it easier to understand and follow along. I will especially try and focus on some UI elements, which I've gotten feedback that it kind of seems a mystery to what it will be until it's finished.
So I will be using this whiteboard at the beginning of each chapter to add some screenshots here so that you can see what our final build for this specific chapter will be. Right, so this first chapter is quite simple. Our goal is to just get a project running. As I've already said, we first have to choose our runtime, which will either be Node.js or Bun. And we also have to choose our package manager, which can be npm, pnpm, Yarn or Bun.
As you've already noticed, I have highlighted bun in these two places and in my little legend here I've marked that as highly recommended. Why do I recommend bun for this tutorial? First of all I recommend it because you will get the same environment as I do. Basically, I will be using BUN in this tutorial, which means that I will be running BUN commands. So if you want to follow along exactly as I do, it will be much easier for you to use BUN as well.
The second reason is we're gonna have to run some scripts, which will have TypeScript inside of them and some ES6 imports. Now, I am aware that in the newest versions of Node.js, we are capable of doing just this, but I'm certain that we can do it with BUN. I'm not 100% sure if Node.js can do it now. I've seen some updates around this, but I am certain that we can do it with BUN. So for example, we're gonna add a little seed script to add some elements to our database and we can easily run that script using BUN.
Whereas with Node, at least in previous versions, we would have to add a proper TypeScript configuration and we would have to change ES6 imports to the old require methods and all of those things just to run a simple script. So for that reason, again, Bun gets a point for me. And the last reason is we will have less issues in regards to dependency issues when it comes to React 19. So if you are not aware React 19 recently came out and while that is great not all packages that we will be using in this tutorial have upgraded their peer dependencies to use React 19. What happens then is that certain package managers will throw errors or warnings when you try to install a package inside of your React 19 project which will be the case for this tutorial because we will be using React 19.
For example, npm will straight up throw an error and prevent you from installing until you add a flag ––legacy-peer-depths or ––force. This is something that I did in my previous tutorial Google Docs Clone and it was just a hassle to write every single time. Yes, you can store these flags inside of a npmrc file, but you can already see just how much we're complicating just to install a simple package. When it comes to Yarn, it will throw a warning, but it will install the package. But for Bunn, it will simply work.
You won't even notice that there are any dependency issues inside with react 19 and the package we are trying to install great so if you want to use bun you will have to visit bun.sh or simply Google bun runtime. So yes bun is both a package manager and also a node compatible runtime. So I'm gonna of course show you everything I have installed in my system so you can follow along but go ahead and visit the website if you don't have bun if you have Linux and Mac OS you can use curl to install a bun and if you use Windows go inside of your PowerShell and go ahead and run this. There are additional ways you can install if you go into docs here. I think maybe Windows users might have some questions especially if they don't use PowerShell.
You can install it using npm as well also known as the last npm command you will ever need. So go ahead and run this command if you are on a Windows and you don't use PowerShell. If you use PowerShell you can just run this right on Mac OS and Linux. You can also do this, you can also use brew, you can use Docker or you can simply use curl right here. Once you've done that, what you're going to do is just confirm that you have bun installed.
As you can see, this is my current bun version. I'm also going to show you my Node version just in case if you don't have Node This is a bit of a conflicting advice. I'm giving you now because I just told you we're gonna use BUN. We're gonna use BUN. I would recommend you have Node installed as well.
I think majority of people watching this tutorial will have Node installed, right? But in case this is your first ever venture with JavaScript, you have chosen a pretty hard project to start with, but I will support you through this journey. Go ahead and install Node.js. I think that installation is even simpler or as simple as BUN. Just find the download latest long-term support.
So confirm you have Node version, confirm you have BUN version. You should not be getting errors for any of these. Next go ahead and confirm you have NPM just in case. So when you install Node you will also have NPM installed and for BUN, well BUN is both the environment, I mean the runtime and the actual package manager. So this confirmed that we have that right.
Now let's go ahead and let's see. So I'm just going to add some ticks here, right. So we selected our runtime here. Let me increase the opacity. There we go.
We selected our package manager. We learned why we're going to be using bun. Now let's establish some basic bun commands and for this we can actually already start creating our Next.js project. So here I am on the documentation page of Next.js And here we have some system requirements. So first of all, it says that we need to have Node.js 18.18 or later.
So that's why I advise you to install Node.js just in case. I usually don't tell this in my tutorials because I assume a lot of people already have this installed, but just in case. It's never wrong to have Node.js installed. Just make sure whatever version you see here is not lower than whatever is written on the documentation right here. And you can see that the operating system supported are macOS, Windows and Linux.
And we're going to be using this command right here to install our Next.js project. But before you go ahead and run this, you will notice that it's using NPX. So this is a Node.js specific or npm specific command, but I just told you we're going to be using bun in this tutorial, so I will show you an alternative and we are also not going to be using this at latest I will explain why in a second. So let's go ahead and learn this. Whenever you see npx in bun world that's equal to bun x right And whenever you see npm install in bun world that's equal to bun add and then name of the package.
Great! So we just learned this basic bun commands right here. So now let's say I want to see what is the latest version of this package, because we want to install an explicit version here and not just use at latest, because Next.js can introduce a lot of breaking changes in a very short period. So I don't want my tutorial to get outdated by the time you found it here. So this is what we're gonna do.
We're just gonna copy this and instead of using npx we're gonna be using bunx and then we're just gonna add create-next-app at latest and then just dash dash version and there we go we now have the version so this is the version I will be using throughout this tutorial which means in order to run this command let's finally do it now npx I'm sorry bun x create next app at 15.1.6 right here so instead of latest we'll be using this specific version I'm gonna call this project new tube like this. I'm going to be using TypeScript. I'm going to be using S-Lint. Quick tip, You can select this answer using arrow keys. So yes for TypeScript, yes for S-Link, yes for Tailwind, yes for source directory.
Sometimes this will be defaulted as no, so be careful. Move it to yes and then press enter. Make sure you select the app router. This is absolutely crucial because we will be using and leveraging server components very much in this tutorial. I have not yet used TurboPack.
I've heard great things about it in development mode right so this is TurboPack for development which is supposed to make your dev environment much faster. I would recommend selecting no for this tutorial purely because I will not be using it right so I cannot guarantee you how different of a project you're going to have if you select yes. So keep it no for now. I will not be customizing my import alias. I like the at sign.
If you don't know what an import alias is, I will show you that once we open up our project. But just select no for now. And there we go. Bunn install will now be running and installing all of our dependencies. There we go.
We now have installed our new project. As you can see, it's inside of my users and then whatever my folder was where I ran this command right here, bonnex create next app and inside of here we have new tube so I can now go inside of change directory new tube like this and there we go you can see some files here and now we're of course going to open this up in visual studio code or whatever is your IDE of choice. I would highly recommend going with VS code simply so you can have all the same extensions as I will. So I'm going to go ahead and click on open here and I will select new tube which is my newly created folder here. If you get this prompt you can safely press yes.
I trust the authors here. All right, so now let's take a quick peek at our structure here. So outside of, I mean in the root of our project, we have all of these config files. We will later revisit the tailwind.config.ds This one is actually quite important, right? So this configured Tailwind and enabled the Tailwind in this specific folders, pages, components, and app, right?
But later on in the source folder, we're gonna add some new folders here, which will not be covered by Tailwind by default. So we're going to have to remember that and quickly go back here so we can learn how to enable that as well. But we're not going to concern ourselves with that right now. I just want to bring your attention that even though we will mostly be working inside of the source folder here, there are some useful things that we are going to tinker with throughout this project. Right?
Ensure that you have the Tailwind file. Ensure that you have the TS config. Basically, everything that you see here you should have as well and of course we have our bun lock file because we opted to use a bun. Inside of your source folder you should have the app folder which is basically our router. So our app folder is a reserved folder in which there are certain reserved files like layout and page which are used to create routes.
So if you go ahead right now and do bun run dev or npm run dev if you choose to use npm you can already visit this at localhost 3000 so let's quickly go ahead here and visit this page I'm just gonna zoom in a bit and there we go so I am currently past p.m. Here so my entire project is in dark mode. Yours might be in a light mode. You might be seeing a white background here. Don't worry about that.
We're going to default to one of those later. Great! So we now have our basic project here but I don't want to end the chapter here purely because we added this add Shazam UI. So we learned how to use the exact version, we got familiar with the structure and now we have to add ShadCN UI and just take a peek at some useful VS Code extensions. So let's go ahead and let's go and for now I would recommend you shut down the app and instead go ahead and visit ui.shatcn.com or simply Google Shatcn UI.
And inside of here, we're gonna go inside of the docs here. So what is Shatcn UI? As you can see, it is not a component library. It's a collection of reusable components that we can copy and paste into our apps. And I honestly think this is my favorite way of building our own component library.
So let's go ahead and head into installation. Let's select Next.js for the framework and now we're gonna go ahead and install this and as you can see here it will tell you something. If you're using Next.js 15, see the Next.js 15 plus react 19 guide. Let's click on that just to see what's going on. So you're gonna see what's written here is exactly what I've told you in the beginning.
If you are using NPM you can install chat cn unit dependencies with a flag. So basically that's what I wanted to avoid. The Chassis and CLI will prompt you to select the flag when you run it, but there are no flags required for PNPM, BUN or YARN, right? So what's happening? React 19 at the time they were writing this was in release candidate.
Now it's no longer in release candidate as far as I know it's completely out but this is still in progress basically. All the other packages need to update their peer dependencies to include a react 19. Right so if you use npm this will happen you will get this kind of errors and then you have to choose either using force or legacy peer depths. So that's why I was highly recommending to use bun because bun will not have any issues for this. Great!
We can now go back to the installation. Sorry for this hijacking, I just wanted to explain once again. So let's go ahead and select the bun here and let's copy this command. So bunx dash dash bun shatc and at latest init. But before we run this, this is what I will actually do.
I will just copy chat.cnn at latest and I will do bannocks chat.cnn at latest dash dash version. So I just want to see the version of the latest chat.cnn and that is 2.1.8. Great! So now we can go ahead and run this command here. But instead of using at latest we will use at 2.1.8.
So the reason I want you to do that is so you don't have any surprises, right? These things can change very fast and I want to ensure a certain level of longevity in my tutorials, so no matter when you found this, I want you to have the same experience. So for this style, you can select New York. For the color, as the base color, you can select neutral. You can select yes for CSS variables right here.
And this should add some new components. Components.json, it should modify Tailwind config, and it should update this globals.css file and it should also create source lib utils. Let's go ahead and quickly check that out now. So as you can see I have six modified files here and all of those are exactly what we've written. So we have the new components.json, which is basically a configuration file for chat.cn.
We have modified package.json with all the necessary new files here. We have modified tailwind.config.ds. And yes, if you go to the bottom here, you will notice that there is an error here. I've never had this error causing me any problems. It did not cause problems with the build, so I will leave it as it is.
I will not fix it or anything. So let's see what else has changed. Globals.css was modified, as you can see. And now, what will happen, what you're going to notice now, is that you should no longer have a dark or light mode it should always be light mode so if you go to one run dev right now and if you revisit your project just make sure you refresh it there we go now it's in light mode If yours was already in light mode, you probably didn't notice any changes. But for example, for me, I was in dark mode and now it is light mode.
Great! So you have officially and successfully installed Shat-CN as well. And now let's wrap up the chapter by learning some useful VS Code extensions here and just confirming whether Tailwind works and maybe learning how to add some components. So let's go ahead and do this. Let's go inside of source, inside of our app folder and inside of page.tsx.
So what you see on this page is what's written inside of here. What I'm gonna do is I'm gonna remove everything from my return method. I'm gonna remove the import and I will start from scratch with a little div here and the paragraph Hello world Like this, so you should just see a small text. Hello world written here. Now, let's try out some tailwind So I'm gonna give this a class name font bold and text rose 500 Let's go ahead and try it out.
There we go. Hello world and text rose 500 like this. Now I'm gonna go ahead and go inside of my extensions here and just go ahead and look at Tailwind CSS IntelliSense. There we go. So I would highly recommend that you have this extension.
I'm going to click install again like this and I will reload my window. Looks like something's happening. Yeah, it didn't exactly load the first time. But now you can see that this extension, Tailwind CSS IntelliSense, which we have just installed, is very useful. First of all, you can already notice that it will tell you which color this is in case you are not familiar with its variables.
But the second useful thing is that when you hover over something you can see the exact CSS. So if you're not sure, if you type a unknown style, You have no idea is this from Tailwind or not. You can hover over it and if nothing pops up, this is not Tailwind. This is not a valid class name. So that's how you know if you have typos, for example, text roses, you can see that this is obviously something wrong here because Tailwind is not telling you anything about it.
And you also have some auto-correct here like this. Great, so Tailwind is confirmed to be working and now let's just wrap it up by installing the components we need from ShatCN. So in ShatCN UI here, you can install each component individually, right? So you only use those that you actually need. But it is actually much easier for us to install all components at once, simply because we're just going to do it now in this first chapter and we're not going to think about it for the rest of our tutorial.
So we don't have to remind ourselves, oh, what was the version that I was using? Right? So this is what we're gonna do then. I'm gonna shut down my project. I'm gonna do bunx dash dash bun chat-cn at 2.1, 2.1.8 add dash dash all.
I believe this is the correct command and I think that this will add all the necessary components that I will need. There we go. So you should now have all of these components added to your project. It says 50 files for me at least in this version right here. It has also updated some config, also updated some globals here.
So I'm gonna do bun run dev again. I'm gonna go inside of here and I will refresh my localhost and I'm going to try in the root of my page here to import a button for example. Let's import button from components UI button. So this is an alias. This is what I was talking about.
So instead of having to go dash dash components, right? Obviously this isn't that all that horrible, but if we were deeply nested in some folder, we would have to do this, this, this, right? All the way to find it. But with an alias, we can just use this because alias defaults to our source folder. So whenever you add the at sign in your import, it will act as being in the source folder.
So you can then easily go inside of this components, which was just created because of this command we run. And inside of here, you can see the source code to every single component. This is what I think is super cool with chat C and UI because the source code is not obfuscated inside of the node modules as it is with other component libraries but instead you can make it your own. So I'm just gonna go ahead and remove the paragraph from here and I'm going to render this button and say click me like this and there we go we now have a button which says click me right here and I can go ahead and give it a variant of destructive, for example. And now you can see it has a different variant.
I can also go directly inside of this button. So what I did was I pressed command and pressed inside. Or if you're on Windows, it's control and then go inside. Or you can go inside of source components UI and find the button. And inside of here, you can modify anything you want, right?
For example, inside of here, we have the variants. So if I were to add a new variant and give it the background of purple 500 with a text of white. That's it, I can do that. So now I'm gonna go here and I'm gonna change this to variant new. And there we go, that's my new variant right here.
That's how simple it is to build your own component library. And you can do the same thing for the padding, the roundedness, anything you can imagine. The names of this, if you don't like default, destructive and want to call it, you know, some kind of different semantic way, you can do that. Nothing is preventing you from doing that. And now you can remove this new style if you added it as I did and you can see that it will immediately throw an error here like hey you can't do that that does not exist.
Great so that was a quick intro I believe we covered a lot about how we're going to be using all of this. And we just added some useful VS Code extensions here. Great. I think this is a great start. So what we're going to do in the next chapter is, well, you're going to see in the whiteboard, which will come.
Great, great job.