Best NextJS Folder Structures | Beginner - Intermediate - Advanced

A lot of people struggle with organizing their Nex. js apps. They tell themselves that they will eventually organize their project, but all that means is that they will end up having a components folder with 100 different files.

And what's the problem with that? Well, if you ever want to build a website that has any chance of scaling, then you have to understand how to properly structure your projects. And this is exactly what I will be teaching to you in this video.

We will go over three different folder structures for the same app from beginner to advanced. And if you already have a website up and running, I have a question for you. Do you ever feel like your cloud platform is holding you back?

Maybe you've hit limits on collaborators, run into surprise bills, or wasted time juggling multiple services just to get one app online. It's frustrating and it slows down your team. And that's where today's sponsor, Savala, comes in.

It's an all-in-one platform with no artificial limits, unlimited collaborators, unlimited parallel builds, and no restrictive tiers, so your team can scale without worrying about pay walls. And the best part is Savala runs on Google Kubernetes Engine in 25 regions for extremely world-class reliability. Plus, it bundles everything you need under one roof.

That means managed databases, object storage, instant preview apps, and advanced pipelines, all with usagebased pricing, so you only pay for what you use. And also, Seavala is backed by Kinsta. That means that you're going to get enterprisegrade security and real developer support when you need.

So, if you're interested in checking out their easy to use platform and actually start building, try Savala today by clicking the link in the description and you'll get $50 in free credit. Again, thank you so much Savala for sponsoring this video and let's dive in. Okay, so before I show you guys the beginner, intermediate, and advanced folder structure, uh we built this app over here.

Uh it's a mocked website using XJS and we built the same app using all of the different folder structures so you guys can more easily understand the difference between them. And what this is is a simple events community events planning app. So you can obviously create different events uh and users can go ahead and click on those events, see the events and RSVP if they want to.

They can see the list of different events and so on. So this is just a simple website. It has different parts of it, different aspects.

There's like your profile page, there is uh the events tab, uh create event page, and there's also some marketing stuff like the about page and the FAQ. So, I think this example would be good because it will exemplify what a real production website would look like, right? There's going to be routes that are authenticated like the profile routes and the create events routes.

There's going to be some routes that are for marketing, like I said. And uh uh the way you structure that in your project is going to differ a lot. So this is what we built.

Now let's get into the beginner folder structure. And here it is. This is how I would structure a beginner Nex.

js project. Now I want to start every single one of these uh examples that I'm going to be showing you guys uh with explain to you guys when I would recommend you to use this. So I would recommend you to use a beginner folder structure like this one.

If either you are a beginner of course by the name or if you are any other type of developer that is building a small project or maybe just trying to spin up an MVP in one or two days and your main purpose is to ship fast. So what a lot of people get confused with is they see this as being a beginner folder structure, right? And they imagine that this is just for beginners.

But no, this can also be the folder structure you use for building applications that you just simply want to develop faster, right? And uh I don't see a problem with that at all. This is how you create an XJS project and this is probably what you're most used to because most YouTube tutorials will have a similar folder structure.

So what am I talking about here? What what is the bulk of this folder structure? So obviously we have here a app folder, right?

And this app folder what you would do is you would keep all of your routes in each their each of their individual folders. So keep it simple. Create the routes inside of the app folder.

Create the different pages and maybe you'll have route groups like I have here the dashboard route which has inner routes inside of them as you can see. But each of them simply have a page of. tsx a tsx inside of them, maybe a layout, and all of them would be probably server components.

Now, that means that if you ever need any client functionality, like any client components, you would put them in this generic and general components folder. And here, you would put all of the different uh components that aren't routes in your project, including, for example, stuff related to forms, maybe a button that is a client component, right? because you need an on click and even your navbar as well.

So, keep it simple. Put all of them over here. Not much organization.

Obviously, these components are used in this routes over here. Some of them may be only used once. Uh but we're keeping them all inside of there cuz that's easier for us to quickly know where our stuff is.

Also, we would probably see a shared uh lib folder. So, we would have here some helpers. Like if you're going to have a database, you might have a function for a file with some database information.

Here I'm literally just providing mock data, but you might have a fetchers file, right? Some some way for you to deal with how you're fetching your data. Uh some utility stuff like uh the class name function that you have from Tailwind merge, stuff like that.

And it would all exist here and you would just reuse it whenever you need inside of your project. Now you would also have an API, right? that API would exist in this API folder.

It would just have simple routes that you would create post and get requests inside of it and then obviously call them directly inside of your application. Now the core idea here is uh being fast, right? So this is what most people think of when they think of an XJS app, right?

There's an app folder with routes. There's a components folder with UI. There's a lib folder for helpers.

Maybe there's a types folder if you're using TypeScript. And there's always obviously a middleware. In this case, we're just having a a simple middleware here.

Uh nothing really big, but this is what you would picture. And this is good because it's easy, it's familiar, everyone knows, and it's really easy for you to just quickly spin up an MVP for maybe a project that you're launching, validate your idea, see what people think, and get feedback. Or if you're a beginner, this is also really good because you can practice with thousands of examples out there of people doing the exact same thing as you and you will actually eventually get better and be able to make the decisions on your own.

Now, there's some pros and cons that I want to address here. For example, the main pro pro is that this is super easy to learn, fast to build, and there's basically no folder structure, right? It's just minimal amount of folders and organization.

Now, the cons is that obviously this gets really messy as your features grow. Why? Because picture this.

We have this component over here, right? The event card. Now, let's see where this component is called.

This component is called only in the events list, right? It's only called here. Now, why do we put this in this components folder?

Cuz usually, if you want to reuse it, it's a card, right? You could, but right now we're not doing that. But as our project grows, imagine in the future you just kept adding more components to this components folder and eventually this components folder has like 100 components, 100 different files and you don't know where this event card is when you're looking for it to use it or maybe you're even in this uh events list component and you see this and you're like, "Oh, where is this?

" I mean, you can obviously click here, but you got a bit lost, right? It's good to have everything uh contained uh parts of your website be divided by different uh purposes in them and you'll see that more as we progress in the different folder structures. Also, this is extremely hard for you to test because everything is so grouped together that nothing is in isolation.

So, it's difficult for you to actually predict the behavior. And if you're against testing, I'm a bit against sometimes, you know, sometime some testing is is good, some testing is bad. But I think that if you're going to put out a production level app, I think some testing needs to happen.

And in a beginner project, you don't have to worry about that at all. So that's why not having stuff in isolation and having stuff just grouped together is totally fine. Now, let's get into the intermediate structure.

This structure immediately, as you might notice, is a bit different. There's way more folders than we had before. Uh there's some stuff, for example, there's testing in here.

Uh but we'll we'll get to that in a second. I want to first talk about when I would recommend using this and I would say that this is probably the stage in which most people will be in uh other than the beginner. I would say like if you're if you're trying to pro produce an app and publish it for people, this is probably what you would see.

So I would use this if you are uh trying to actually grow an app. Uh it doesn't have to be a huge app. It doesn't have to be a huge, you know, product.

It could be uh maybe a team of like even two people, two to six people. uh it I would use this if you're building a a website which has way more pages than normal. So we have here an app folder and uh because we have more pages.

You see we have a lot more routes over here. Each of them might even have individual internal routes. Uh we are actually organizing them.

Now some people don't like putting parentheses uh for uh folders in X. js also known as route groups because they are not really routes. They're just for organization purposes.

what I think is super useful like if you're going to have a lot of different parts of your website, you want to organize them together. So like every route related to authentication will be put inside of the O route group. Every uh route that is part of the dashboard, so like the events, the host, the profile will be part of that.

And everything related to marketing such as the pricing page, maybe the FAQ, the about page will be part of the marketing route group. So that's one of the biggest parts of uh the intermediate project a lot of focus and organization and the main idea with this folder structure is to add very clear boundaries. So for example we have you know you guys know already what the app folder is right just to render your routes you guys know what the API folder is right just to make uh server routes but then what would we do with this so as you're building your app in an intermediate folder structure you would create all of your database o business logic inside of this server folder and for each of them you would abstract it by creating a folder for each specific type of service.

So I have here an O folder for everything related to that. Then you can have a uh DB folder, right? I would personally if you're building a a more intermediate project probably use some sort of uh good reliable database and some sort of ORM to support that database.

Uh which in this case I would always recommend Prisma. I have a huge course on it if you guys want to check it out on YouTube for free. Uh but I love Prisma and I would probably use something like that.

And we have all the configuration files here as well. Then I would also recommend that you use some sort of server state manager, right? Something in the realms of for example react query, something like that.

Uh uh and for that you would probably want to organize your your API requests uh in whichever way that makes sense to whichever framework you're using. Since I I just mentioned tense query, there's obviously the concept of mutations and uh the concept of queries. So I would organize my mutations and queries maybe in a way like this.

And obviously there's also the services. If you have any any type of uh backend services, any type of vendors that you guys are dealing with in your project uh such as Stripe, all that kind of stuff, you might put them here as well. Now this is just the back end.

This is what how you would organize your back end. But when you're building your front end on top of the different routes that you have over here, there the routes have inside of them different features, right? The homepage might have 10 different features inside of it that should all exist in a different part of the project because they all are independent.

So the features is used for creating userfacing and user interacted pieces of UI. So these over here would probably contain a mix of some small UI plus server actions. So like the RSVP feature is a feature, right?

It has a UI, right? It has the uh maybe the part of the website where you can RSVP and then it has obviously all the stuff that comes with it like the backend interactions that you would need to make and so on. There's also the events which is way bigger because this this whole thing is all about events, right?

Create an event, reading an event, editing an event, all that kind of stuff would exist in a folder like this. that could involve some server actions that would exist here or that might involve some UI that would exist here like that event card that I mentioned in the previous uh folder structure and also any hooks that you might want to reuse throughout this individual feature. So this is the main idea.

We are dividing our UI of our project into folders that will group everything related to it together so that it's way easier for us to know. Now, if we go ahead and see the event card component, right? If we were to, and now we're reusing it in many places, but if I were to go over here and see it appearing on this page, right, I saw this event card over here, I knew I I would probably know immediately that it is part of the features folder in the events folder in the components and then there's the event card.

So, that's the main idea here. Now one thing as well I would say this are smaller but obviously we would have the same live folder that we had before and also if you're building an intermediate project I would highly recommend giving a lot of time into thinking about caching in order for you to optimize your obviously your API requests make your website load faster with nextj that is a big issue so I would recommend spending time on that and then there's some other stuff that are more like not a requirement I like uh a UI folder right and this is different from for example the UI folders we have on the features because these are more generic components that you just reuse. Like every time you have a button that you need to use in your project, you create a button component that is unique to your project so that you don't have to rewrite the same logic multiple multiple times.

An empty state is another one like there's going to be multiple scenarios in your app where you're fetching data and maybe there's no data there and you have to account for that case. In both cases, you want to put a unique empty state that will appear in your app. Maybe it's a little image, maybe it's a text, whatever you want, and just reuse it like that.

And all that will exist inside of the shared UI folder. Now, the main pro uh for this specific uh folder structure is that out of the three, in my opinion, is the most fun to play with because I think it isn't too messy and it isn't too uh strict, right? So, this could scale to real products.

There is the ability to test. Uh so we have a logic here that is uh abstracted enough that you can isolate it and test it. I forgot to mention we have here our test folder, right?

And uh there is a clearer boundary between the client and the server, right? We have our server stuff uh inside of our routes if we need to and also in this server folder over here. And we have our client stuff if we need to as well inside of the components folder.

And if we ever need to have any server interaction uh on top of that, we have some server actions. Now the cons is that obviously it's it's more of a con related to the beginner's fold folder structured which is there's more folders more conventions uh because of the way you're structuring this there might be a risk of duplications if if you're not really careful with how you're establishing your boundaries how you're establishing like when you're creating folders you really want to be careful with where you're creating folders if it makes sense and I feel like this is an issue that grows even more when we get to the advanced one uh but it's definitely a cost that you have to pay from the benefit of having a less messy project. Now, the main difference between this one and the last one is that we move a lot of the logic that was existing inside of here into the features folder, into the server folder, and so on.

Now, we get to the advanced structure. And the advanced structure is uh one that I don't personally recommend. Uh I don't personally recommend.

I think that this is what I would expect to see in a big company. You know, something in the realms of this, not maybe not exactly the same thing. And that's something I wanted to tell you guys like don't take everything I say to the letter.

You know, best practices isn't an exact science. So, if you're going to structure a project, sometimes it works better for your team in a different way. So, if that's the case, do that.

So I'm just trying to gather what I have learned from building in beginner, intermediate, and advanced projects from what I understand to this day. So this folder structure is an advanced folder structure. What I would recommend is that you only use this kind of stuff if uh you see benefit in it.

And usually you will see the benefit in building something like this if you have a big product and a big team. So something that maybe have multiple surfaces, may maybe multiple parts of the app, maybe even subsites to your app that uh they're not related. Uh a project that would involve complex interrations uh would involve maybe a complex backend, stuff like that.

And the the core idea here that I I structured is the idea of having entities, features, processes and widgets. Now those four over there the names don't really matter but uh the these names are known in the industry and they take shape in different ways but this structure follows this way. In this project you would obviously create your routes the same way as we mentioned before.

the exact same routes, you would put them over here and this is all that this would be. Just create the routes. Now, inside of those routes, there's different parts of them.

And those parts of them are distributed and organized throughout the entities, features, processes, and widgets. Now, what are they? Well, the entities is the raw data and rules.

Now, we'll start with the features. The features is related to what the user can do. So in this app there's a lot of things that the user can do like for example the user can create an event they can pay stuff they can RSVP to an event they can search stuff and these are small abilities that are glued to a UI that that glues a UI with data often through for example a server action in order to make that ability be usable by the user.

So that's what a feature is. And here you can clearly see that we have here the create events feature, the host payouts feature, the RZP event feature, and the search feature. Now in the events project, I didn't uh like manually create the folders or the files for each of these folders cuz uh the example project that we used over here uh wouldn't fully match what this folder structure looks like, but it's still running through here.

Now, this is what the features folder is. Now the entities folder is a bit different. This is the raw data your app knows about.

So like this would involve uh simple shapes and rules like uh what is the event look like? What is the model of it? Uh what is the RCP look like?

What what does the user look like? And by model I usually mean like you maybe define some interfaces, define how parts the fields of what an event is relates to a user, stuff like that. And this would be really useful as well because it would mainly be used for stuff like reusable TypeScript types.

Now the uh widgets folder is in my opinion the most important one because this one is where you create the UI. So there is pieces of the UI that you would consider a widget. Now what is a widget?

Now a widget is a name given to reusable UI blocks. So, not a small feature, but like a huge block. So, if you think of YouTube, for example, YouTube has the recommendation feed, right?

There's a bunch of videos showing up on the right when you're watching YouTube. So, that feed appears multiple times on this app. And that isn't just one component.

That's actually a like a a block of components, a block of UI with multiple things including the video recommendations, uh the ability to scroll through it, the titles of the videos, stuff like that. And whenever YouTube needs to just put that at a different page, you can just reuse that widget. So that's what a widget would be.

And you it's it's reusable blocks of UI that you just copy and drop at different screens. they will show things that they don't own any big logic or any routing but they are pieces of UI that you can rely on and put whenever you need to. Now the last one is the processes.

Now the processes uh it really doesn't matter like it depends on which project you're building. I added here because usually if you're building an advanced project you would need to have some behindthe-scenes job. So this is kind of like stuff that you can run on a schedule.

Chron jobs, nothing related to UI, stuff like sending emails every day for a notification, uh cleaning data, syncing with services, all that kind of stuff. Uh you would definitely have something like this, especially the sending email stuff. You might want to run that in the schedule.

And I would put that uh background processes inside of this folder. Now, the rest of this would be uh similar to what we've mentioned on the intermediate. Uh there's going to be a test folder.

And in here you would do different types of testings, right? So that's that's a big thing that you do in big companies. There's integration testing.

Uh there's unit testing and there's end to end testing. So if you're not familiar with each of them, uh basically you uh the most basic explanation I can give you is unit testing you test like you force test uh what you expect from different endpoints, different functions, stuff like that and you manually mock the data. Integration testing, you actually make API requests and you test what the result is.

And end toend testing is is sometimes not not that common uh depending on the type of app you have, but it's basically when you uh validate that the entire app uh is working from uh the front end to where the data is stored, all that kind of stuff. Uh there's also snapshot testing because this is a front end uh application which you could do it as well. I'm going to close this.

I usually this is more of a backend testing kind of stuff but if you are interested in in testing the front end I would do it in the widgets folder or whatever whichever UI folder you have I would do it more specific to each file. Now the main pro here is that this would scale and also it's good for team ownership. So like if you're working in a company right that that has multiple teams h each team would own a different part of this project.

everyone would be coding on the same uh project, right? Because it's the front end of the website. It's not like it's a each person can create their own micros service and then they can own the whole service with the front end.

Everyone has to share the same codebase. H but even though you're sharing the same codebase, you will own different parts of it like different widgets, different uh features, stuff like that. And this allows for more easily doing that.

It also again has strong boundaries which makes it easier for you to test. uh and there's some performance patterns built into it as well. Now, some of the cons is that it has a steep learn learning curve.

there's a lot of abstraction and a lot of uh spending time organizing your project and stuff like that which can c it's just more boilerplate and this is 100% an overkill for most apps because you don't need to have uh like if you're if you're building an app alone you don't have to organize it so much just because no one else will be you know where everything go is you know like uh unless you're building for other people you don't have to do this but I like to imagine that I think it might be useful for some of you who has hasn't worked on a advanced project yet to at least have an idea of how it would look like. Now, should you immediately go ahead and change all your projects to match the folder structures that I mentioned? No, 100% not.

If you build a a project with a beginner folder structure to validate your app, it could take you one to two days for you to actually merge it. If you build a project with a beginner folder structure just to quickly validate your app, you could then take one or two days to just move that into a more advanced folder structure that makes it more organized. You don't have to do that since the beginning.

Now, that's basically it. I really hope you guys enjoyed this video. If you enjoyed the video, please leave a like down below and comment what you want to see next.

Again, thank you so much Savala for sponsoring this video. Really appreciate. If you guys want to check them out, please click the link in the description and I'm sure you guys will enjoy their product.

Now, if you want to see any specific video of mine, please leave a comment down below and let me know. I'll respond to as many comments as possible. And thank you so much for watching and I see you guys next time.