본문 바로가기

README 작성하기
Next.js 13과 redux/toolkit, styled-components 등으로 북마크 기능이 들어있는 쇼핑몰 앱을 구현한 프로젝트이며, 설명에 필요한 코드만 최소한으로 서술되었습니다. :
(1) gitHub - README 및 전체 코드 보러 가기   
(2) 프로젝트 요구 명세서 보기 (해당 프로젝트 첫 포스팅)
 

GitHub - Doyu-Lee/COZ-shopping: This project consists of a main page, a product list page, and a bookmark page, offering respons

This project consists of a main page, a product list page, and a bookmark page, offering responsive design and features like random and bookmarked product display, filtering, modal windows, bookmar...

github.com

 


 

 

README는 프로젝트 구조 설명 및 프로젝트 관리 방법에 대한 기본적인 문서화(documentation)를 목적으로 한다.

  • README는 프로젝트의 루트 디렉토리에 Readme.md의 파일명과 형식으로 위치한다.
  • 프로젝트에 대한 간략한 설명과 사용 방법, 설치 및 설정 방법을 기술한다.
  • 즉, 프로젝트를 이해하고 사용하는 데 도움을 주는 역할을 한다.

 

README를 잘 작성하는 방법

 

How to Write a Good Readme File for Your GitHub Project의 내용을 중요한 내용 위주로 번역해보았다. 

 


 

README를 작성할 때, 프로젝트의 'what', 'why', 'how'에 대해 대답할 수 있어야 한다. 

  • 이 프로젝트를 시작하게 된 것인가?
  • 해당 프로젝트는 어떤 문제를 해결할 수 있는가?
  • 프로젝트를 통해 무엇을 배웠는가?
  • 이 프로젝트의 장점은 무엇인가? (만약 프로젝트의 기능이 많다면 '기능' 섹션을 추가하여 내용을 정리하면 된다.)

 

README에 들어가야할 내용은 다음과 같다.

 

1.  프로젝트 이름

프로젝트의 주요 목적이나 목표를 이해하는데 도움을 줄 수 있다.

 

2. 프로젝트 설명

  • 애플리케이션의 기능
  • 사용한 기술을 선택한 이유
  • 직면했던 문제점
  • 향후 구현할 기능들

 

3. 프로젝트 설치 방법

프로젝트를 설치하고 실행하는 방법에 대한 단계별 설명을 제공한다.

 

4. 프로젝트 사용법

프로젝트를 사용할 수 있도록 스크린샷 등을 활용해 간단한 지침과 예시 등을 서술한다.

또, 사용자 인증이 필요한 프로젝트라면 인증 정보에 대한 내용을 남겨놓는다.

 

5. 공로

프로젝트를 팀 또는 조직으로 진행한 경우에 깃헙 프로필과 SNS 링크가 걸린 협력자 / 팀원들의 정보를 기재한다.

또, 참고한 자료나 튜토리얼이 있다면 여기에 포함시킨다. 

 

6. 라이센스

라이센스는 보통 README의 마지막 섹션에 기재가 된다.

  • 라이센스는 다른 개발자들이 해당 프로젝트에 대해 얻을 수 있는 권한에 대한 것이다.
  • 라이센스의 종류는 여러가지가 있으며 가장 일반적인 것은 GPL 라이센스이다.
  • 이는 다른 사람들이 코드를 수정하고 상업적 용도로 사용할 수 있게 한다.
  • 라이센스를 선택하는 데 참고하면 좋을 사이트 : https://choosealicense.com/

 


여기까지가 README에 필요한 최소한의 요구사항이며, 아래의 내용들은 필요에 따라 선택적으로 추가할 수 있는 내용이다.


 

7. (선택) 목차

README가 매우 길다면 프로젝트를 쉽게 탐색하기 위해 목차를 추가하는 것이 좋다. 

 

8. (선택) 배지

배지는 필수는 아니지만 다른 개발자에게 내가 무엇을 하고 있는지를 알려주는 간단한 시각적 도구이다.

  • 예를 들어 사용한 스택을 링크하고, 프로젝트에 대한 간단한 통계(포크 수, 기여자 수, 열린 이슈 현황 등)을 보여준다.
  • 배지는 자동으로 업데이트 된다.
  • 배지를 추가하려면 여러가지 배지를 호스팅해주는 다음 사이트를 방문하면 된다. : shields.io

 

9. (선택) 기여 방법

오픈 소스 프로젝트를 개발하는 경우에 기여하는 방법 등을 추가할 수 있는 섹션이다.

 

10. 테스트

더 나아가 테스트 코드를 작성하여 해당 테스트 코드의 예제와 실행 방법을 제공한다.

  • 프로젝트가 문제없이 잘 구현되었다는 것을 증명하여 사용자에게 신뢰감을 줄 수 있다.

 


 

그 외에도 상호작용적이며 정보 전달을 위한 README를 위해 항상 최신 내용으로 유지시키고, 영어로 작성하는 것을 추천한다.

 

작성한 README 내용

 

프로젝트를 마무리하고 작성한 README 내용을 마크다운 형식에 맞춰서 블로그에도 옮겨왔다.

  • 티스토리 마크다운이 호환이 안 되는 부분이 있어서 최소한으로 일부 수정했다.
  • 처음에 프로젝트 플래닝을 할 때, README를 제일 처음에 써야 하는 걸로 생각하고 이슈 카드를 제일 위에 위치시켰는데 프로젝트를 계속 진행하다보니 회고의 형식으로 프로젝트를 마무리할 시점에 README를 작성하는 것이 가장 자연스러우면서 효율적이라는 깨달음을 얻었다. 

 


 

솔로 프로젝트 - 나만의 쇼핑몰 앱

 

코드스테이츠 SEB FE 44기 솔로 프로젝트 과제로 북마크 기능이 들어있는 쇼핑몰 앱을 구현했습니다.

 

  • 기간 : 2023.5.13. ~ (진행 중)
  • 프로젝트 요구사항 분석 및 플래닝 :
  • coz-shopping 폴더로 진입하여 npm run dev로 프로젝트를 실행합니다.

 

⚒ 기술 스택

redux/toolkit

nextjs

tailwindcss

styled-components

 

📢 주요 기능

  • 메인 페이지 : 무작위 상품 4개, 북마크한 상품 4개를 전시합니다.
  • 상품 리스트 페이지 : 모든 상품을 전시하며, 필터링 기능이 있습니다.
  • 북마크 페이지 : 북마크한 상품을 전시하며, 필터링 기능이 있습니다.
  • 공통 기능 :
    • 반응형 페이지로 구현했습니다.
    • 상품을 클릭하면 해당 상품과 관련된 모달창이 뜹니다.
    • 상품의 북마크 아이콘을 클릭하면 아이콘이 활성화 되며 북마크 페이지에 상품이 보관이 됩니다.
      • 한 번 더 누를 경우 아이콘이 비활성화되며 삭제가 됩니다.
      • 북마크 추가 아이콘을 누르면 '북마크에 추가되었습니다', 다시 해당 아이콘을 누르면 '북마크에서 삭제되었습니다'라는 문구를 담은 알림 토스트가 출력이 됩니다.
    • 상품 리스트와 북마크 페이지에서 무한 스크롤이 됩니다.
      • 요구 조건에 따라 서버에서 전체 데이터를 먼저 받아와 로직을 구성하였습니다.
      • 반응형 화면에 따라 예를 들어 4개가 보이는 화면에서는 그에 맞춰 마지막 줄을 4의 배수로 상품이 채워지도록 구현했습니다.

 

💬 요약

1. 커스텀 훅을 활용한 Header & Footer 섹션 기능 개발

  • Next.js의 Layout.js 파일을 활용하여 고정된 Header & Footer 섹션을 생성했습니다.
  • UI를 고려하여 hover 시에는 햄버거 버튼이 약간 확대되고, 클릭하면 드롭 다운 메뉴가 나옵니다.
    • 드롭 다운은 메뉴 혹은 해당 컴포넌트 바깥을 클릭하면 사라지도록 구현했습니다.

2. redux/toolkit의 createApi를 사용하여 데이터 받아오기

  • Redux Toolkit의 createApi를 사용하여 API를 관리하기 위한 설정과 엔드포인트를 정의했습니다.
  • createApi함수를 사용하여 'productApi'라는 API 인스턴스를 생성한 후, useGetProductsQuery 등의 훅을 내보냈습니다.
    • useGetProductsQuery는 전체 상품 데이터를 받아옵니다.
    • useGetProductByCountQuery(number) 는 number 만큼의 상품 데이터를 받아옵니다.

3. redux/toolkit을 사용하여 전역 데이터 관리하기

  • 상품의 북마크 아이콘을 클릭하면 업데이트된 북마크된 상품 데이터들을 localStorage에 저장했습니다.
    • isBookmarked : true 데이터를 추가하여 북마크된 상품 데이터들의 북마크 아이콘이 어느 페이지에 가든 일관적으로 활성화되도록 구현했습니다.
  • 북마크 아이콘을 클릭하면 토스트 알림이 뜨도록 구현했습니다.
    • 전역 데이터 관리가 필수적이지는 않지만, 간결한 코드 정리를 위해 ToastReducer을 생성하여 데이터를 관리했습니다.

4. 무한스크롤 기반 반응형 페이지 개발

  • 상품 리스트와 북마크 리스트 마크업과 반응형에 맞춰 CSS 적용을 했습니다.
    • breakpoint는 임의로 1000, 700, 400px로 최대한 UI를 고려한 레이아웃을 구성하였습니다.
    • flex-start를 적용하여 4개의 상품이 있어야 할 공간에 1개의 상품이 있을 때 (북마크 컴포넌트) 레이아웃이 깨지지 않도록 구현했습니다.
  • 무한 스크롤은 프로젝트 요구사항에 기반하여 서버에서 전체 100개의 상품 데이터를 이미 받아온 상태로 가정하고 진행했습니다.
    • 실제로 무한 스크롤을 구현한다면 IntersectionObserver을 사용하여 스크롤 감지에 따른 데이터 fetch로 로직을 구현해야 되기에 향후 리팩토링을 하고자 합니다.
    • viewport 넓이에 따라 추가로 보여줄 상품 개수를 계산하여 한 행에 4개의 상품이 있는 경우 다음 데이터를 불러올 때 4의 배수에 맞게 불러오도록 하였습니다.

5. 컴포넌트 재사용을 위한 상품 컴포넌트 생성

  • 컴포넌트들을 최대한 재사용하고자 단일 상품 컴포넌트를 생성하여 4가지 타입에 따른 이미지 소스와 텍스트 등을 각각 추출하여 적용했습니다.
  • 북마크 기능을 위한 별표 아이콘 컴포넌트를 생성하여 추가하였습니다.

 

💖 해결 중인 문제들

Next.js 13 관련 문제

1. layout.js에서 page.js로 props를 내려 보내는 방법

  • Next.js 13은 폴더 기반 라우팅으로 폴더 구조 자체가 라우팅을 정의하는 방식으로 동작합니다.
    • app 폴더 바로 아래의 layout.js 파일은 여러 페이지에 공통으로 적용되는 구성 요소 및 스타일을 포함합니다.
    • Next.js 13 버전의 폴더링 구조를 활용하여, '상품 전체 페이지'와 '북마크 페이지' 위의 공통된 카테고리를 layout.js 파일로 구현했습니다.
    • 문제는 layout.js에서 특정 카테고리 버튼을 클릭하면, '상품 전체 페이지'와 '북마크 페이지'에서 데이터 필터링 로직이 구현되어야 하는데, layout.js에서 각각의 페이지인 {children}에 해당하는 page.js로 props를 내려주는 방법을 찾고자 노력 중에 있습니다.

1-1. 해결하고자 한 시도들

    • 물론, 컴포넌트로 만들어 페이지 컴포넌트에 import 하는 방법과 redux를 활용한 데이터 전역 관리 등 해결방법이 있습니다.
    • Next.js의 폴더링 구조를 활용한 문제 해결 방법이 있는 지에 대해 좀 더 알아볼 예정입니다.
    • Next.js 공식 문서에서 Layout을 통해 데이터를 내려보내는 것을 불가능하다는 것을 알게 되었습니다.
Passing data between a parent layout and its children is not possible. However, you can fetch the same data in a route more than once, and React will automatically dedupe the requests without affecting performance.
It's supposed to be just an "UI that is shared between multiple pages" of a segment (page.js, loading.js, etc).
  • 출처 : stackoverflow 질문
  • 따라서, 간단히 기존 방식인 카테고리 컴포넌트를 생성하여 props를 내려주었습니다.

 

▶️ 향후 리팩토링 예정

  • 타입 스크립트로 프로젝트를 리팩토링
  • IntersectionObserver 또는 Virtualized 라이브러리를 사용하여 무한 스크롤 기능 다시 구현
728x90
⬆︎