클린 아키텍처로 Next.js 스타터 키트 구조화하기

발표자는 Next.js에서 계층화된 아키텍처를 구현하여 유지 관리와 관심사 분리를 위해 코드를 구조화하는 방법을 설명합니다.

### Next.js 스타터 키트에서 클린 아키텍처 구현하기
* 🏗 밥 아저씨의 "클린 아키텍처" 책에서 영감을 얻은 클린 아키텍처 접근 방식을 구현하려면 **코드를 컨트롤러, 사용 사례, 엔티티 및 지속성**과 같은 다양한 계층으로 구조화하여 코드 유지 관리성을 유지하고 프로젝트를 유지하기 어렵게 만드는 종속성을 방지해야 합니다.
* 📦 "프레젠테이션 레이어" 또는 "컨트롤러"에는 서버 액션과 같은 **Next.js 관련 코드**가 포함되어 있으며, 깔끔한 분리를 유지하기 위해 정의된 경계 오른쪽에 **비즈니스 로직과 분리**된 상태로 유지해야 합니다.
* 🧑 서버 액션은 **프레젠테이션 계층에서 컨트롤러 역할**을 하며, 사용자 상호작용을 처리하고 해당 사용 사례를 호출하는 역할을 담당합니다.
* 🧩 비즈니스 계층에 위치한 사용 사례는 **애플리케이션의 핵심 비즈니스 로직을 캡슐화**하며 권한 확인 및 비즈니스 규칙을 포함하는 경우가 많습니다.
* 💾 지속성 계층은 데이터 저장소에서 데이터를 저장하고 쿼리하는 메서드를 제공하여 **데이터가 어떻게 지속되는지에 대한 세부 사항을 추상화**하는 역할을 담당합니다.
* 🔄 깔끔한 아키텍처 접근 방식을 사용하면 팀 전체가 따를 수 있는 공통 패턴을 만들 수 있으므로 **새로운 팀원을 온보딩**하고 코드베이스를 유지 관리하기가 더 쉬워집니다.
* 📂 컴포넌트와 이를 사용하는 페이지 등 관련 코드를 **같은 디렉토리에 함께 배치**하면 코드 유지 관리성을 개선하고 프로젝트를 더 쉽게 이해할 수 있습니다.
* 🛡 '관심사 분리' 원칙을 적용하면 계층 간에 민감한 정보나 구현 세부 정보가 유출되는 것을 방지할 수 있으며, **데이터 전송 개체(DTO)를 사용**하면 이러한 분리를 시행하는 데 도움이 될 수 있습니다.

so I think it's been like a week since I've published a video on my channel, and I figured I should probably get something published out there before the YouTube algorithm thinks I'm no longer relevant. So I want to talk about the structure of my code and how I kind of architect the code for my next.js starter kit. Um, you can kind of take what you want from this. You can in the comments, you can say that this is dumb, you can say, hey, I agree with what you're doing, maybe we can have a discussion about it and just learn from it. A lot of the stuff I'm going to be showing in this video do come from an idea called clean architecture. There's a book called clean architecture written by Uncle Bob. We apply this, or we try to apply this as best as possible at work. So we have something called like controllers, use cases, entities, and you kind of structure your code in different layers. And there's certain rules that you follow so that you don't have dependencies that cause your project to be a little bit

more unmaintainable. There's also like a layered architecture approach where you basically have like a presentation layer, a business layer, a persistence layer, and a database layer. This is also kind of what I'm doing on my starter kit, which I'll kind of walk you through the different layers that I have applied. I highly recommend that you do something like this on your projects. Like I've seen a lot of videos and tutorials where people are just like doing uh Prisma calls or drizzle calls or SQL calls calls directly in their react server components when the page loads. And although that works, I just don't think it's a very long-term maintainable solution. Uh, what you want to do is just apply some type of layered architecture so that you have more control over like who can read the data, who can manipulate the data, and you can kind of test your business logic separately from all the nextjs code. Okay, so let's just draw a little bit. So in my project, I'm trying to do a layered architecture type of

thing right. So, we have Next.js. And to help kind of exemplify what we're doing, um, we are going to follow a use case where I'm an admin or an owner of this group, and I want an admin or owner to be able to modify the text on the info page. Like over here, if I say hello world, I save this. I want other users who are not admins or owners to be able to see this text when they go and view this group directly. So, in terms of that use case, what we just did in Next.js is what you probably know is I'm using server action. So, let's just go ahead and say we have a server action. I'll make a little box here. I'll say server action, and this is one of the layers. I'll call this a presentational layer. You may also call this a controller. It doesn't really matter. The point is you want to keep all your Next.js specific code to the left of this line, right? You don't want React cache methods or unstable cache.

methods bleeding over onto the right side of the line. You don't want revalidate path or revalidate tag bleeding over cuz now at this point you don't have nice clean uh separations between like what's in charge of the presenting and the controlling of your code and what's in charge of the actual business logic. So that leads me to my next point. If I consider a server action kind of like a controller, if you were to look at this layer architecture, the presentational layer would probably be like react or your react server components that render out the page when you invoke an action. Again, that's kind of calling a presentational layer controller. Again, if you were to look at the clean architecture Circle, your controllers in your presenters are all in this interface adapters, right? So the user needs to do something. They are going to invoke some type of controller, invoke some type of adapter, and in our case, I'm basically going to say that a server action is a form of a controller. Again, feel free to call me out in the

comments if anything I'm explaining doesn't seem right but this is just how I kind of think about it. So when a user clicks on the save changes, that invokes a server action, which again is still in this Next.js layer over here. So let's kind of look at the code. I have a page, and I click on a button, and it calls an action. Let's try to figure out where that's happening. I have an action here called update group info action. Now, something that I'm doing in my codebase is I want to make sure that everything that goes in and out of this action is parsed right. I want to make sure that the stuff that's sent in it matches a certain type of structure. I want to make sure that the group ID sent in is a number. There is an info that's sent in that is defined. And once I get that information, I can kind of trust it and start running some controller type of code. And again, notice that my actions, this is where I keep revalidate path or revalidate tag.

or redirect all of the next.js SL uh react specific code. I would probably keep it inside of This Server action. Now if you're curious how I'm using an authenticated action, I'm using a library called Zsa, which allows you to basically create middlewares. Where, for example, I have this authenticated action, I create a procedure, and anytime I want to create an action that requires authentication, all I do is I just run some code, make sure that the, you know, the cookie set, the session is set. I also do some rate limiting just so that all my authenticated endpoints are just rate limited by that user ID. I don't want people trying to maliciously abuse my systems, and then I return the user, right? So again, this is still all in the controller presentational layer. If we were to go back to this diagram now, at some point you'll see that after I've done the parsing of the input, which comes from a form or whatever, I'm calling something called a use case. This is just my nomac claure of like how I

like to denote this stuff, and this comes heavily from the Clean Architecture book. So all of my actions invoke use cases, and these use cases lead us to the next point I want to make out, and that is the business, uh, business layer. A business layer, and then inside of this business layer, the Clean Architecture believes that it calls them use cases or slash interactors. Okay, let's just look at this little diagram real quick, and you'll see he calls the little orange-red circle use cases, and then that points to application business rules. Okay, so from my perspective, what is a business rule? What are concerns of the business logic? Well, the action, all it's in charge of, is basically taking in, figuring out what the authentication methods are, maybe you're using JWT. Maybe using session storage, doesn't matter. The business layer does not care about that. All it cares about is that you're passing in the correct data, um, that it would expect. So in our case, this update group info use case, this needs a group ID and an info, and it also takes in an

authenticated user again. This thing doesn't know if we're using JTS or sessions. It just gives me a user object, and I'm going to use that user information to figure out if a user should have access to update the group info. So what this does is basically we're going to pass over some user information, the group ID, whatever, and we're going to invoke a use case again that I called update group info use case. I might as well go back to this one and change this one to have a name. Just call it this action here. So this action is going to invoke this business layer use case interactor, and this is where you want to run some type of authorization check. So in my group finder application, I have a lot of role-based authorization checks in place. You can be an owner or an admin of a group, or you can just be a member of a group. If you're an owner or an admin, an owner can actually go and delete the entire group. An admin just has the ability to modify some info.

they have the ability to come in here and maybe promote other users to an admin or demote users, etc. But the owner has, you know, very special privileges that you have to encode this in business logic somewhere. And so, how this works is basically this use case is where you're going to run your, you know, authorization checks. Is this user an owner or an admin? And then if they are, you want to be able to allow them to update this information. So, let's look at the code because it's actually super, super simple. So, basically, we first fetch the group by group ID. If there is no group, I throw an error. And again, you should not be throwing any type of Next.js specific errors here. You should not be calling redirects or anything. Keep it simple, throw errors or return some type of like error objects if you need to. And then finally, I do another check that says if I'm not the group owner, go ahead and throw an error that has unauthorized. And then finally, if everything passes, we just go ahead and

update that group info using that info that was passed in. Now, technically, there is more to clean architecture. If you look at this diagram, there's something called entities. And I'm avoiding entities just to keep it simple for my, you know, one-man team starter kit project. But at some point, you may want to encode business rules to say info can only be 1,000 characters, right? That is business rules that the business people can define. And I know when I say business, like I'm just talking about myself because this is like a one-man project. But when you work on a bigger team, like there's people who are going to define how large, how much data some of the stuff can be, what is the shape of this data? Is it a first name? Does it need to be all capitalized? Does it need to be proper case, stuff like that? And so sometimes what you want to do is you want to encode this information in something called business entities. And those entities can have validation rules themselves. Okay, now I'm not going to

dive into that because again I'm not doing that. So basically, I just call a method called update group, and this is something called a persistence method. So this is going to lead us to the next section of our code, which is the persistence layer. Okay, let's look at the layered architecture. We are over here. We just talked about the business layer a little bit. Now we're at the persistence layer, and the persistence layer's goal is to basically give you methods that you can invoke for storing and querying data from your data store, whether that be in Postgres, whatever. So we have a method over here called update group. So I'll just go ahead and make a little box here that's going to call update group, going to pass in some information such as a group ID, some info, and there's different ways you can do this. A lot of people use something called like a repository pattern where they'll have like an object called, I don't know, groups, and they'll say update, and they'll pass it whatever information. Something like this, I think, is just not

as friendly to read versus something update group that's just a personal preference. It doesn't really matter, but the point is, is that this layer is responsible for knowing how to write to your database, which in case I'm using drizzle. But something I want to point out is that you don't even know I'm using drizzle, right? The business layer has no concept of what omm you're using, what libraries you're using to actually persist the data. All it knows is that I need to call some method to save this group information, okay? That's been abstracted away about how that actually happen. So let's dive into this code real quick, and you'll see over here I have a data access folder with like all of my tables. I basically have like a one-to-one mapping of a file maps to a table in my SQL database. You can structure this however you want, but the way I typically do this is I have a groups file, and this has an update group function which allows you to basically take any group

ID and just update any parts of it right. And so now you start seeing some code that might look familiar to you, which is drizzle orm. So if you go up to the top here, you'll see that I am just defining like a drizzle orm connection. And in fact, let me, uh, how do I go to the definition here? I think just scroll up. You'll see I'm importing this from DB, which is bringing us some drizzle orm stuff, okay? So this persistence method, this persistence layer knows about how to write and persist the data, which if you look at a layered architecture, now we're hitting the database layer, something that we're using a library we're using knows how to write data. Let's just go ahead and put another line here. And this is going to write directly to a database. Just draw a database symbol here. Here we go. I'll just say post CR 'cause that's what I'm using. So if we zoom out a little bit, this is the pattern that I try to follow in my applications. This is just the way

I've been brought up when learning how to code. People smarter than me have taught me this pattern. I believe them and I follow the pattern too, not blindly, but I do try to follow it because I personally think it is useful. Some of the reasons why I think following either clean architecture or layered architecture or some type of pattern is, everyone on the team has a common pattern they can follow. If you're working on a project by yourself, I mean you could just raw dog SQL right in your react server components if you want to. I probably would not recommend that because if your project actually takes off and grows, you're going to want to bring in other engineers, and you want a Common Language, such as an architecture, that you can all discuss things about. Now, some teams and projects like to make this even more complex, which I'm on the fence of. A lot of teams will, in between these two layers, they'll do something called data transfer objects (DTOs) to make sure that certain things Never Bleed over. So, what I mean by bleeding

over so for example in the business layer. Let's say you're fetching something from a persistence layer. An update group happens to update the group, but then return the whole group object back. You could potentially have a bunch of extra fields on this database that you haven't actually like cleaned up. You could have like a group name, a group display name, all this other stuff, and you may not want that to ever bleed over into your business layer, right? So, sometimes what you do is you'll create a data transfer object so that all the data is basically sent through a mapper to make sure that you only return the things that are necessary from your persistence layer back to your business layer. And again, you want to make sure that you only return certain things from your business layer back to your controller or back into your react server component so that you don't leak sensitive information or information that's not a concern of any of these layers. One good example I've seen is a lot of people who use MongoDB a lot of the times the unique

identifier for your IDs is underscore ID, and they'll start bleeding that over into every single layer. You can actually look at the network request and see, Oh, all the entities have an underscore ID on them. I'm going to assume you guys are using MongoDB, right? Because that wasn't really abstracted way too well, and using something like a DTO could potentially help prevent leaking information about your underlying architecture of your system. Maybe you don't want people to know you're using MongoDB because that opens up more security attack vectors of how they can abuse your system, stuff like that. So that's kind of how I would recommend at least loosely following a project. The only DTO stuff I end up doing is with these actions over here. I can actually put an output as well, and I can specify what the output needs to look like. So over here, I can say, Well, I just want this to return nothing. I could say void or undefined or something, and that at least gives me a little bit of certainty because Zod is going to

verify that whatever I'm returning here, it has to match undefined. If I were to accidentally take the group that was being returned here and let's just say like name is Bomb, notice that I get some typescript errors that says, Hey, you're returning some information where you're not supposed to be returning that, because you specified an output of undefined. Something like that can be very useful. And again, this is basically a DTO. It's just that we're using libraries that just automatically do it for us, and I don't want to waste a bunch of time writing the mapping code and writing the DTO objects with classes and stuff like that. Now, before I wrap up this video, I do want to kind of touch a little bit about the directory structure of my projects. I try to collocate as much as possible. So if I'm looking at a page right here, for example, I'm on my group info page, everything that's on this page should be in the same directory as my info route. I don't like having a separate components.

folder where I put all those, and then I import them. I want all my components that are related to co-occur in this directory because I think it makes the project a little easier to maintain. At work, we do an approach where we have like every folder holds different things, and those things are separated by type, and you end up having this folder that has 500 different files in them, and there's like no good way to really understand like what is using this thing, okay so if it's not an actual res sharable reusable thing then I would just co-locate it. For example, typically server actions have stuff like this, like revalidate path, which means they are very tightly coupled to the page or the route that you're on, so it makes sense to just put your actions directly in this folder. Also, with components, this is the only place in this entire application I have a component that looks like this, so I'm not going to go and find my components directory and put it in there. I'm going to co-locate it so that if I were to

onboard someone under this project. They can also have a common Convention of like okay. I'm looking at the info page. I have 95% certainty that every component that's needed for this info panel is probably going to be right in this directory. Now another thing I'm still trying to figure out how I want to approach this is basically the react server components. When you hit a page, you typically need to load some data. And so the way I've been doing this is I'll just call these use cases directly here before I call the use case. I will basically get the current user from a session and then I'll call the use case and pass it the current session. And then also I'll pass it the um whatever arguments I might need. And that'll return some data for me right. And I can kind of throw errors inside the react server component where I could actually have like an errors. TS file handle that and display something else. The kind of exemplify what I mean. So this is the info page. It takes in a group ID which

is loaded from the URL here, and I basically take that and I call a git Group by ID use case. Let's just go ahead and go through the whole flow real quick. Quick so you understand, uh, I call this git Group by ID use case. In our case, I probably should do some type of authorization here to make sure that there's no like sensitive data being leaked. But um, again, you can kind of search for a lot of these groups publicly, and that ends up calling a get group by ID method, which calls a drizzle method to get the first group by an ID. Okay, and I don't see any issues with doing this as long as you just, you know, make sure you're passing in the user sessions again because you're calling the use case during your react server component, and all the business logic is kind of encapsulated there. Now, something that I might at some point end up needing is when you have a complex tree and you have to call the same method multiple times in your react server components. Typically, what you want to do

is you want to call a cache method which is built into next. I'm sorry this is built into react actually um so you can bring in a cache method from react and you can wrap your functions with this cach uh Factory function basically so that as it's traversing your react server components if it finds the same method it's just going to use the cach results for that individual request that your user made and then on the next request if a new user comes in it hits the same page brand new cache it's not going to reuse the old stuff okay so in some cases you may want to do that and I might actually add a new folder here or a new file called loaders and then I would probably just make a new fun function here called like uh get group by ID loader and then you could basically um you want to do this I could just set this to Cache like this and then I could just have this taken a group ID like so and then you know call the use case in here goad and say return get

group by ID use case, something like that. And then also in the loader, you could potentially get the user. So get current user like this so that I can pass it in. And then obviously, we want this to be an asynchronous function. So we do this. If for some reason you do end up needing to like wrap stuff with the Next.js, like try to avoid going into your use cases, your business layer, and like trying to add cache methods here because again you're breaking that convention of like now you're running a React code inside your business layer. Okay, so technically if I were to do that refactoring, I could just call that loader here. And then I can get that information, information and use it. So I want to talk on one last point as to why I think this is more maintainable. And the reason is if you keep all your Next.js code out of your business layer, what you can do is if down the road you decide that you know what server actions isn't it server actions is just not

worth doing. It's causing more headache. I'd rather go back to using form Hooks and go back to React Query and just hit API endpoints. Well, the refactoring involved with doing that is very simple because now you have this method that doesn't care about anything in Next.js. It doesn't care about how you're handling your actions or your post requests or mutations. It just needs some input. And so if later on you decide, you know what, I actually want to make this an API endpoint, well, it's super easy to just have a new API endpoint directory and invoke this, which makes it very convenient and a lot more maintainable. Another thing that I've seen in some projects is if you don't do some type of approach like this, you end up taking your business layer, like your logic that defines when a user should read something, and you end up putting it everywhere. Like you'll take this, you know, there's some certain rules that you need to check to see if a

user has access to get a group, and you're like, oh, I'll put it in this react server component, and then later on you'll decide that you need that same logic, and you'll put it in another place. Maybe you also need it in front of the API, but then you have all this business logic that's kind of sprinkled out throughout your controller and your presentational layer, which you'll start updating in one place, and you'll forget to update it somewhere else. And then it's just a big headache because you've basically spread out all of your core logic throughout your entire application. It becomes very, very hard to maintain and understand, and also to even switch off of in the future if you needed to for some reason. Um, anyway, I've been rambling for a while now, so I hope you guys enjoyed watching this video. Again, I just wanted to get something out there for you all, and hopefully this elevates your knowledge in coding a little bit. Again, leave a comment if there's a different approach you like to

make your applications. If you're using Next.js with server actions, let me know. We can have a discussion about it. Other than that, have a good day. Happy quing.

How I structure my next.js applications

This channel is a collection of various programming videos, tutorials, projects, talks, or anything software engineering and programming related.  If you are new to coding and want to learn how to program or get a job in the industry, be sure to subscribe to my channel.  There is a lot of great content on this channel to help you out in your coding goals.

Web Dev Cody

js에서 계층화된 접근 방식으로 코드 설계하기

이 동영상에서는 밥 아저씨의 클린 아키텍처 원칙에 따라 계층화된 아키텍처를 구현하여 Next.

js 특정 코드를 비즈니스 로직과 분리하는 방법에 대해 설명합니다.

발표자는 프레젠테이션 계층에서 서버 액션을 일종의 컨트롤러로 사용하여 Next.

js 특정 코드를 격리하는 것을 강조합니다.

이 접근 방식을 적용함으로써 데이터 조작과 비즈니스 로직의 테스트를 Next.

js 코드와 별도로 더 잘 제어하는 것이 목표입니다.

사용자가 '변경 사항 저장'을 클릭하면 Next.

js 계층에서 서버 동작이 트리거됩니다.

코드베이스는 클린 아키텍처의 원칙에 따라 사용 사례를 호출하기 전에 입력을 구문 분석하고 예상 구조와 일치하는지 확인하는 데 중점을 둡니다.

사용 사례로 표시되는 비즈니스 계층은 동작에 사용되는 인증 방법과는 무관하게 비즈니스 로직 및 예상 데이터와 관련이 있습니다.

그룹 정보 업데이트에서 사용자 액세스 및 권한 관리하기

이 프로세스에는 사용자 정보를 사용하여 그룹 정보를 업데이트할 수 있는 액세스 권한을 결정하는 작업이 포함됩니다.

권한 확인은 그룹 내 사용자의 역할(소유자, 관리자 또는 회원)에 따라 이루어지며, 각 역할마다 권한이 다릅니다.

코드는 그룹을 가져오고, 권한 검사를 수행한 다음 사용자의 액세스 수준에 따라 그룹 정보를 업데이트하는 간단한 순서를 따릅니다.

소프트웨어 아키텍처의 지속성 계층 이해

지속성 계층은 데이터베이스에서 데이터를 저장하고 검색하는 방법을 제공하여 비즈니스 계층에서 데이터 저장 세부 정보를 추상화하는 역할을 담당합니다.

이 계층은 종종 리포지토리 패턴을 사용하며 사용되는 특정 데이터베이스나 라이브러리와는 독립적입니다.

데모 코드에서 지속성 계층은 각 데이터베이스 테이블에 대한 파일을 포함하며 데이터 조작을 위해 드리즐 옴을 활용하여 궁극적으로 PostgreSQL 데이터베이스에 직접 씁니다.

소프트웨어 아키텍처 패턴을 따르는 것의 중요성

클린 아키텍처 또는 계층형 아키텍처와 같은 공통 아키텍처 패턴을 따르면 팀에 공통 언어를 제공하고 향후 확장성을 용이하게 합니다.

데이터 전송 개체(DTO)를 구현하면 소프트웨어의 여러 계층에서 민감한 정보의 유출을 방지하는 데 도움이 될 수 있습니다.

DTO를 사용하면 특히 네트워크 요청에 MongoDB 사용량을 노출하는 것과 같은 경우 추상화와 보안을 개선하는 데도 도움이 됩니다.

프로젝트 구조화 및 컴포넌트 관리

자동 DTO 생성을 위해 라이브러리를 사용하면 매핑 코드를 작성하지 않아도 됩니다.

관련 컴포넌트를 같은 디렉토리에 배치하면 프로젝트를 유지 관리하고 새로운 팀원을 온보딩하기가 더 쉬워질 수 있습니다.

React 서버 컴포넌트를 사용할 때, 컴포넌트 내에서 직접 사용 사례를 호출하고 오류를 처리하는 것이 데이터를 로드하는 잠재적인 접근 방식이 될 수 있습니다.

js에서 캐시 메서드를 사용하면 캐시된 결과를 동일한 메서드에 재사용하여 개별 사용자 요청의 효율성을 향상시킴으로써 React 서버 컴포넌트의 성능을 최적화하는 데 도움이 될 수 있습니다.

보다 지속 가능하고 체계적인 구조를 유지하기 위해 비즈니스 레이어와 Next.

js 코드를 분리하여 React 코드를 비즈니스 레이어에 직접 통합하는 것을 피하는 것이 좋습니다.

로더 함수를 통해 캐시 메서드를 구현하면 "get group by ID loader"와 같이 복잡한 트리와 여러 메서드 호출을 효과적으로 관리하는 데 도움이 될 수 있습니다.

js에서 통합 메서드 사용의 이점

js에서 통합된 방법을 사용하면 특히 API 엔드포인트로 전환할 때 리팩터링과 유지 관리가 쉬워집니다.

이 접근 방식은 애플리케이션 전체에 핵심 로직이 흩어지는 것을 방지하여 장기적으로 더 이해하기 쉽고 유지 관리가 쉬워집니다.

통합된 방법을 구현하면 궁극적으로 개발 프로세스를 간소화하고 Next.

js 사용자의 코딩 지식을 향상시킬 수 있습니다.