테블리 프로젝트 폴더 구조 설계

Intro

사이드 프로젝트를 개발하면서 특히 신경썼던 부분들을 정리해본다.

기술스택

프로젝트에서 사용한 기술 스택은 다음과 같다.

• 코어: React, Next.js, TypeScript
• 스타일링: shadcn/ui, tailwind
• 상태관리: jotai
• API 통신: React-Query, axios
• Package Manager: pnpm
• 로깅: Sentry

폴더 구조 설계

Next.js에서 폴더 구조 설계 방법에 정답은 없다. 하지만 이전의 개발 경험들을 미루어봤을 때 많은 양의 파일들 사이에서 수정해야 하는 코드를 찾는 일은 언제나 괴로웠기에.. 그리고 다른 사람과 의사소통을 할 때에도 필요한 코드를 찾는데 시간이 오래 걸리는 것은 소통의 불편함을 가져왔다.

이런 부분을 최대한 방지하고자 폴더구조를 설계할 때 코드의 맥락을 계속 생각하면서 설계하고 프로젝트의 초반에 원칙을 분명하게 세우려고 노력했다.

/public

public 아래에는 프로젝트에서 사용되는 fonts, images 등 asset 파일들을 넣었다.

/app

app폴더는 Next.js에서 라우팅 기능을 지원해주는 폴더이다. /app/blog-input이라는 폴더를 만들고 안에 page.tsx를 만들면 /blog-input이라는 url의 페이지가 만들어진다.

/app에서는 전역으로 사용하는 style과 error 페이지를 만들어 사용했고 url이름을 표시하는 폴더 안에서는 최대 section 단위의 컴포넌트까지만 사용하도록 하였다.

/src

/src에서는 다시 constants, components, hooks, lib, store, types 등으로 나눈다. 해당 폴더에는 프로젝트 전체를 관통하는 파일들을 넣는다. 예를 들면 useThrottle, useResize등은 프로젝트 전체에서 사용 가능하기 때문에 /src/hooks아래에 넣는 방식이다.

/src/components

components들은 page url 기준으로 사용되는 컴포넌트들과 그렇지 않은 컴포넌트로 나눴다.

url과 상관 없이 사용되는 컴포넌트들은 /shared와 /ui에 분류했다. shadcn/ui에서 받은 raw한 컴포넌트들과 Text처럼 ui 표시에 중점을 두는 컴포넌트들은 /ui에 추가하였고 KakaoAdfit 컴포넌트처럼 프로젝트 어디에서나 사용할 수 있는 컴포넌트는 shared에 추가했다.

page url을 기준으로 사용되는 컴포넌트들은 /blog-input, /blog-recap 하위에서 ui의 컴포넌트들을 조합하고 페이지에 필요한 로직들을 추가해서 만들었다. 이때 추가한 로직이나 타입 등은 /hooks, /lib, /store, /types 등으로 /src에서 나눈 것과 동일한 형식으로 다시 나눴다.

예를 들면

현재 프로젝트에서 해당 부분은 section tag로 이루어져 있고 /app/blog-recap 폴더에 속해있다.

‘이 블로그 방문하기’ 부분은 단순 텍스트로 이루어져 있기 때문에 /ui의 Text컴포넌트를 사용했다.

하단 부분은 blog-link-card라는 이름으로 /components/blog-recap 하위에 넣었다. blog-link-card에서 필요한 부분은 다음 두가지이다.

• 서버에서 온 프로필 사진, 블로그 이름, 블로그 주소 데이터
• 블로그 주소에서 프로토콜을 제외한 나머지 부분

카드를 렌더링하는 데 필요한 데이터들은 /components/blog-recap/store에 분류하고 readonly atom을 이용해 가져왔다.

블로그 주소에서 프로토콜을 제외하는 로직은 /components/blog-recap/blog-link-card의 utils.ts 에 넣었다.

openapi-generator-cli

사이드 프로젝트를 개발하면서 사용했던 라이브러리 중 하나는 openapi-generator-cli이다.

open-api-tools는 OAS에 따라 개발된 API 스펙 문서에 따라 클라이언트에서 사용 가능한 타입들을 자동으로 생성해주는 도구이다.

우리 사이드 프로젝트에서는 api schema 문서를 open api로 받아볼 수 있었고 이를 이용해 openapi-generator-cli를 사용하여 shema의 타입을 자동 생성할 수 있었다.

사용 방법

npm init을 통해 만든 프로젝트 폴더에서 아래 명령어를 실행한다

npm install @openapitools/openapi-generator-cli

그리고 package.json에 다음과 같은 스크립트 명령어를 작성한다.

  "scripts": {
    ...
    "generate": "openapi-generator-cli generate -i {api문서 주소}/openapi.json -g typescript-axios -o src/api/generated"
  },

그리고 터미널에 npm run generate를 입력하면 /src/api/generated 폴더 안에 api.ts, base.ts, common.ts 등 자동 생성된 파일들을 볼 수 있다.

나는 openapi-generator를 이용해 통신함수 구현까지 자동화를 하지는 않았고 자주 변경될 수 있는 schema의 타입을 자동 생성하는 것에 만족하였다.

Outro

프로젝트를 개발하면서 이전에 느꼈던 한계점들을 보완하려고 노력했는데 역시 프로젝트 설계와 적절한 도구 사용은 많은 경험이 필요한 일인 것 같다.

references.

https://xionwcfm.tistory.com/459

https://velog.io/@529539/Nextjs14-TypeScript-Project-Setting-Structure

https://min9nim.vercel.app/2022-04-07-openapi-generator/

https://www.stevy.dev/react-design-guide/

https://github.com/Blazity/enterprise-commerce

https://github.com/SoYoung210/craft

 

ps. 혹시 부족한 부분이나 개선점을 발견하셨다면 댓글 부탁드립니다