[React] 프로젝트 세팅 추천 (ver. 2024, 팀플 사용 중심)(feat. 카테캠)

티스토리 뷰

React

[React] 프로젝트 세팅 추천 (ver. 2024, 팀플 사용 중심)(feat. 카테캠)

단담 2025. 3. 12. 22:22

2024년을 기준으로 (제가) 자주 쓰는 React 프로젝트 세팅을 공유하고자 합니다. 대부분 카테캠(카카오테크캠퍼스)에서 배운것을 따왔어요.
기회가 된다면 CIL로 자동세팅해주는 툴도 만들어보고 싶네요. 제가 유지보수할 자신은 없지만..

도구 선택, 프로젝트 구조 convention 등은 정답이 없습니다. 다양하게 써보고 편한게 있다면 그걸 사용해봅시다

개요

순서는 다음과 같습니다.
다 귀찮다면 그냥 이 github 레포 clone해서 쓰세요

빌드 툴(vite) 세팅
project structure 구성
style 도구 선정

빌드 툴(vite) 세팅

vite 세팅에 대한 공식문서

vite 선택 이유

CRA 사용해보셨나요? 아마 2023년도쯤 React 공부를 시작하거나, 그 즈음 자료를 보고 공부하시는 분이라면 npx create-react-app myapp으로 react 세팅을 해보셨을 건데, 그럼 사용해보신 겁니다.
이렇게 세팅을 하고 npm start를 실행하면 실행되기까지의 시간이 꽤 걸릴 겁니다. CRA는 Webpack이라는 번들링 도구를 내장하고 있는데, 이게 수행하는 빌드 전의 번들링 작업이 오래걸려서 그럽니다. vite는 좀 다른 방식을 쓴다고 하네요. 언젠간 포스팅해보겠습니다.
현재 공식문서에서는 nextjs 프레임워크 사용하라고 권유하고 있네요. CRA가 한물 갔다는 걸 보여줍니다. nextjs 프레임워크에서도 vite 빌드 툴을 씁니다. 그러니 빌드 툴은 vite로 잡고 시작해보겠습니다.

세팅 따라가기

현재 위치 확인: 터미널 켜고 현제 위치가 프로젝트를 생성할 폴더인지 확인합니다.

저는 Desktop/git_project/React_Init에 만들겁니다
vite 세팅: npm create vite@latest . -- --template react-ts를 실행합니다. 현제 위치에 vite 관련 기본 세팅 자동으로 해줍니다.

실행시키면 뭔가 선택해야 하는게 나오는데, 차례로
a. 현제 프로젝트 이름 확인
b. 프론트 기술 프레임워크 확인 -> React 선택해주세요
c. variant 선택 -> TypeScript 선택해주세요
잘 돌아가는지 테스트: 이제 시키는 대로 npm install(필요한 js 라이브러리 설치), npm run dev(빌드. localhost 띄워 줌) 돌려주시면 됩니다.
npm install, npm run dev는 package.json 파일에 관련된 명령어입니다.
npm install은 dependencies, devDependencies에 적인 라이브러리들을 설치해 node_modules 폴더에 넣어주는 명령어이고,
npm run ~는 scripts에 적힌 명령어를 돌려주는데, 그럼 npm run dev는 vite를 돌려주는 명령어겠죠?
곁다리 삭제: 방금 돌린 vite 세팅 명령어는 이해를 위해서 favicon 파일이나, 기본적인 상태 변환 코드 등을 추가로 생성해줍니다. 필요 없으니 삭제해줍시다.

예시 코드

project/folder structure 구성

project sturcture란?

파일을 어떻게 정리할거냐, 를 정한 것 입니다. 예시(React Folder Structure in 5 Steps 2024에서 제안한 내용)를 보자면,

- src/
--- feature/
----- user/
------- profile/
------- avatar/
----- post/
------- post-item/
------- post-list/
----- payment/
------- payment-form/
------- payment-wizard/
------- services/
--------- currency/
----------- index.js
----------- service.js
----------- test.js
----- error/
------- error-message/
------- error-boundary/
------- services/
--------- error-tracking/
----------- index.js
----------- service.js
----------- test.js
--- components/
----- list/
------- index.js
------- component.js
------- test.js
------- style.css
--- hooks/
--- context/
--- services/
----- format/
------- date-time/
--------- index.js
--------- service.js
--------- test.js

이런 겁니다.

기능별로 크게 폴더를 나누고, (≈spring boot의 계층형)
하나의 컴포넌트의 jsx, 스타일, 관련 컴포넌트, 테스트 파일을 하나의 파일에 모으기 (=colocation , ≈spring boot의 도메인형)
최근의 웹 프로젝트 구조들은 대부분 이와 같은 계층형+도메인형 양상인 것 같습니다.

project structure 정하기

위에 소개한 방식을 대부분 따르나, 약간 변형해서 써보려고 합니다.

ㄴ 📁 assets: 이미지 등
ㄴ 📁 components: 전체적으로 쓰이는 컴포넌트
ㄴ 📁 pages
    ㄴ 📁 페이지이름
        ㄴ 📜 index.tsx: 랜더링 될 페이지 컴포넌트
        ㄴ 📜 style 파일
        ㄴ 📜 components(xxx.tsx): 해당 페이지에서만 사용되는 컴포넌트 모음
        ㄴ 📜 tests(xxx.test.ts): 관련 테스트 코드
ㄴ 📁 utils: 전체적으로 쓰이는 도구(타입 인터페이스, fetch 인스턴스 등)
  ㄴ 📁 hooks: 커스텀 훅 파일 모음
  ㄴ 📜 path.ts: 경로 string 모음
  ㄴ 📜 axios_instance.ts: axios instance
ㄴ 📜 App.tsx
ㄴ 📜 global_style 파일

이렇게 정한 이유는 다음과 같습니다.

규모가 작은 프로젝트를 관리하기 위해서는 위와 같이 많은 구분이 필요하지 않습니다. 가능한 기능별 구분을 적게하기 위해 줄였습니다.
하나의 기능을 개발하면 보통 css, jsx, 추가 js코드를 한번에 켜고 작업할 때가 많습니다. 이것까지 계층형으로 구성하면 폴더 열었다 닫았다하는게 상당히 귀찮아집니다. 따라서 colocation(도메인형)을 최대한 따를 생각입니다.
url, style, axios 설정 등은 프로젝트 init단계에서 미리 객체화 해두는 게 좋습니다. 하지 않거나 늦게 하면, 이리저리 하드코딩 되어 흩뿌려지기 쉽기 때문입니다.
component의 이름은 Pascal case convention을 따르는게 좋지만, 파일이름은 snake case를 사용하는 게 개인적으로 보기가 편한 것 같습니다.

style 도구 정하기

다양한 도구들이 있습니다.

css

기본적인 도구입니다. 완전 초짜라면 얘를 먼저 써보는 게 좋습니다.

div.box {
  background: 'red';
}
div.box li{
  font-size: 3rem;
}

scss

css의 중복되는 코드를 줄여준 css 전처리기입니다. css보다 훨씬 낫습니다.

div.box {
  background: 'red';
  li{
      font-size: 3rem;
  }
}

css 프레임워크들

class에 키워드를 적으면 알아서 꾸며주는 도구입니다. 컴포넌트도 제공해주고, 적용이 쉬워서 많이 쓰는 것 같습니다.

bootstrap
tailwind위와 같이 html에 클래스를 작성해 스타일링을 하는 식입니다.
익숙하다면 스타일 관련하여 읽기 편한 코드가 되지만, 개인적으로 html 구조를 읽기 힘들게 만든다고 생각합니다.
nextJS는 SSR 때문에 css-in-js보다 tailwind를 쓰게 시키긴 합니다.
 <div class='box bg-red-500'> <ol><li class='text-5xl'>리스트</li></ol> </div>

css-in-js 도구들

css 스타일을 js 변수처럼 다룰 수 있게 해두는 도구입니다.

emotion-styled
vanilla-extract
styled-component

카테캠에서는 emotion-styled를 썼습니다.
npm install --save @emotion/react @emotion/styled로 설치해 쓰면 됩니다.

그 외

global style, reset css

서비스 개발을 반 정도 끝냈는데, 결과물을 본 사람들이 버튼 모양이 구리고 전체 색감이 별로라고 피드백합니다. 이 때 모든 페이지를 돌면서 버튼과 색을 수정해야 한다고 상상하면 어떤가요?
이런 상황을 대비하기 위해서 전체 스타일 파일을 따로 나누어두는 것이 좋습니다. emotion-styled의 경우에는 다음과 같이 global style 파일을 만들 수 있습니다.

global_styles 파일 생성 및 작성
색상, 글씨 크기와 관련된 변수를 작성하고,
글씨 폰트를 불러오고,
자주 쓰이는 스타일을 적어두면 좋습니다.

import { css, Global } from "@emotion/react";

export default function GlobalStyles() {
  return (
    <Global
    styles={css`
          :root {
            --color-main: #89a06b;
            --font-size-base: 15px;
            @media (max-width: 768px) {
              --font-size-base: 12px;
            }
          }
          button {
            border: none;
            background-color: transparent;
            padding: 0;
            cursor: pointer;
          }
        `}
    />
  );
}

global styles, reset css 적용
- 정의한 global styles를 가져와 app에 넣어줍니다.
- reset css: https://www.jsdelivr.com/package/npm/reset-css. 웹브라우저에서 기본으로 그리는 것들을 지워줍니다. ex) h2 크기, 마진 등

import GlobalStyles from "./global_styles";

function App() {
  return (
    <>
    <GlobalStyles />
    <link href="https://cdn.jsdelivr.net/npm/reset-css@5.0.2/reset.min.css" rel="stylesheet"/>
    </>
  );
}

export default App;

routing 설정

초기 설정자가 미리 해둬야, 다른 작업자와의 컨플릭트가 안납니다.
React Router v6에서는 Routes 컴포넌트 대신 createBrowserRouter를 사용할 수 있습니다.
추가로 라우터를 객체화 해두면, 추후 링크명을 바꿀 때 편합니다.

react-router-dom 설치
npm install react-router-dom
path 객체 파일 작성 ( src/utils/path.ts )

export const RouterPath = {
  root: {
    path: "/",
  },
  home: {
    path: "/",
    getPath: () => RouterPath.home.path,
  },
  somePage: {
    path: "/awesome/:id",
    getPath: (id: string) => RouterPath.somePage.path.replace(":id", id),
  },
  notFound: {
    path: "*",
  },
};

App에 라우터 추가하기

import { createBrowserRouter, RouterProvider } from "react-router-dom";

const router = createBrowserRouter([
  {
    path: RouterPath.root.path,
    element: <Layout />,
    children: [
      {
        path: RouterPath.home.path,
        element: <Home />,
      },
      {
        path: RouterPath.somePage.path,
        element: <SomePage />,
      },
      {
        path: RouterPath.notFound.path,
        element: <NotFound />,
      },
    ],
  },
]);

function App() {
  return (
    <>
      <RouterProvider router={router} />
    </>
  );
}

axios instance 작성

axios는 다른 도메인과 http/https 프로토콜로 요청을 보낼 수 있게 해주는 라이브러리입니다.
fetch라는 기본 선택지가 있지만, 그것보다 간편해서 많이들 쓰는 것 같습니다.
axios 기능 중에는 인스턴스를 만들 수 있는 기능도 있는데, 백엔드 서버가 바뀌었을 때나, 서버 요청 앞뒤로 공통적으로 어떤 동작을 해야할 때 유용합니다.

axios 설치
npm install axios
axios instance 파일 작성 (./src/utils/axios_instance)
- 내용은 깃허브 참고해주세요. -> https://github.com/dandamdandam/React_Init/blob/main/src/utils/axios_instance.tsx

공지사항

최근에 올라온 글

최근에 달린 댓글

Total

Today

Yesterday

링크

TAG more

« 2025/10 »
일	월	화	수	목	금	토
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31

글 보관함

티스토리 뷰