과거, 규모가 작은 개인 프로젝트에 세분화된 구조를 적용하면서 과분리라는 느낌을 받았던 적도 있다. 하지만 코드 리팩토링을 하면서 hook과 service, ui를 분리했을때 얻는 유지보수성의 이점이 훨씬 크다는 것을 깨달았다.

이제는 Gemini와 함께 현업에서 어떤 구조가 많이 쓰이는지, 폴더 구조의 정답이 있는지 알 수 있게 되었다. Gemini는 어디서 폴더 구조를 참고하였는지 탐구해보자.

폴더 구조의 교과서​

Bulletproof-React
Gemini가 말하는 폴더 구조의 교과서로 통하는 레포지토리이다. 이 프로젝트의 핵심은 기능 기반 구조에 있다.

A simple, scalable, and powerful architecture for building production ready React applications.

components, hook 폴더에 모든 파일을 넣는 것이 아니라, src/features/comments와 같이 특정 기능 단위로 폴더를 구성한다. 해당 기능에서만 사용하는 로직과 컴포넌트를 한 폴더에서 관리하는 방식이다.

FSD(Feature-Sliced Design)​

FSD는 여기서 더 나아가 계층화를 통해 엄격하게 의존성을 관리할 것을 제안한다. 가장 큰 특징은 단방향 의존성으로, 하위 계층이 상위 계층을 절대 참조할 수 없게 설계하여 코드 간 순서를 명확히 정의한다.

• App: 앱의 진입점 (Provider, 전역 스타일)
• Processes: 여러 단계가 필요한 비즈니스 로직
• Pages: 실제 화면 단위
• Widgets: 독립적인 큰 단위 (Header, Sidebar)
• Features: 사용자 행동 (좋아요 버튼, 검색 창)
• Entities: 비즈니스 (User, Product, Post)
• Shared: 공통 UI 컴포넌트, 유틸 함수

적용해보기​

리팩토링 과정 중 이러한 폴더 구조를 따라가보고 있다. 기존에는 component 폴더와 features 폴더에 로직이 몰려있었고, 이를 각각 features 폴더 내부로 분산시켰다.

• src/features/template/hooks/useDownloadTemplate.ts
• src/features/template/service/tempolateService.ts

기능을 새로 개발할때 features 폴더 안에 새로운 폴더를 만들기만 하면 된다는 포인트가 중요한 것 같다. 기능을 삭제하거나, 관련 함수를 테스트할때 폴더 하나만 확인하면 된다는 것이 작업에 매우 효율적이고 편리하다.

Hook 과 API를 분리하자​

작은 프로젝트에 이런 엄격한 구조를 도입하는 것이 번거롭게 느껴질 수 있다. 하지만 직접 적용하며 느낀 점은 규모와 상관없이 관심사를 분리하는 습관이 필수적이다는 점이다.

컴포넌트에서 직접 API를 호출하는 대신, service로 통신을 분리하고 이를 커스텀 hook으로 감싸는 구조를 추천한다. 이렇게 하면 나중에 TanStack Query를 도입하거나 낙관적 업데이트 로직을 추가할 때, UI 코드는 단 한 줄도 건드리지 않고 로직만 깔끔하게 교체할 수 있다.

마무리​

그럼에도 완벽한 폴더 구조란 건 없다.
기술은 변화하고, 그런 기술에 맞는 새로운 구조가 등장할 수 있다.
그럼으로 유지보수하기 좋은 구조에 대한 고민을 계속 해가며 학습해나가야겠다.

블로그를 만들며 Next.js를 맛본 뒤, 이거 물건이다라는 생각이 들었다.

배포도 빠르고 리액트랑도 비슷해서, 바로 다음 프로젝트 프레임워크로 선택했다.

그렇게 2명이서 야심차게 시작한 타자 연습 사이트 사이드 프로젝트 TYLE

처음엔 모든 게 순조로웠다.

Vercel에서의 배포는 순식간이었고, 리액트 했던대로 구현도 빠르게 했다.

하지만 프로젝트가 진행될수록 뭔가 이상함을 느꼈다.

1. 이거 use Client 이렇게 많이 쓰면 안될 것 같은데

Next.js가 서버 사이드 렌더링SSR에 강점이 있음에도 사이트 초기 메인화면 렌더링 속도가 너무 길었다.

타자 연습 특성상 실시간 키보드 이벤트와 상태 업데이트가 70% 이상이었기 때문에 화면에 거의 모든 곳에 use client가 필요했다!

2. SEO 쓸데가 없네

검색 엔진 최적화가 장점이라지만, 타자 연습 사이트엔 텍스트 콘텐츠가 없기 때문에

키보드와 글귀만 있는 서비스에서 장점을 발휘 할 수가 없었다.

3. 한글 입력과 렌더링

한글 입력은 자+모음이 합쳐지는 형태라 특수한 경우였는데..
조합 중인 글자가 상태와 동기화될 때마다 불필요한 리렌더링이 빈번하게 발생했다. 또한 엔터 키 입력 시 이벤트가 중복으로 발생하는 등 클라이언트 측에서 처리해야 할 엣지 케이스가 많았다.

결국 서비스의 핵심인 타이핑 로직은 순수 클라이언트 영역이었고 성능 최적화의 핵심 또한 클라이언트 측에 있었다. Next.js의 장점을 살리지 못하고 오히려 아키텍처만 복잡해지는 결과였다.

기술은 도구일 뿐이다!​

고민 없는 기술 도입은 오히려 설계의 복잡도를 높이고 개발 생산성을 저해한다. 트렌드에 따라 Next.js를 선택했지만, 타자 연습과 같이 실시간 인터랙션 비중이 높은 프로젝트에서는 더 가벼운 클라이언트 중심의 환경이 적합했다.

결국 개발자의 진정한 실력은, 프로젝트의 성격에 맞는 적절한 기술을 선택하는 안목인 것이다. 이러한 깨달음을 새기고, 다음 프로젝트에서는 SEO와 초기 로딩 속도라는 목표를 설정하고, Next.js의 기능을 제대로 활용할 수 있는 서버 컴포넌트 우선 설계를 중심에 두기로 했다.

다음 글 : 한번 깨지고 다시 다진 Next.js

초반에는 1시간 정도 걸렸고, 후반에는 2시간, 어려울 때는 3시간까지 문제 풀이에 시간을 들였다.

그동안 프론트엔드 구현에 JavaScript를 쓰긴 했지만 기초부터 체계적으로 배운 건 아니었다. 그래서 메서드 하나하나 알아가면서 풀었는데, 과정을 완료하는 시점에서 보니 각 메서드의 쓰임새를 익히고 문자열과 배열을 집중적으로 공략할 수 있어서 좋았다.

드디어 JS의 기초를 제대로 뗀 느낌 😊😅

Lv.0인데도 쉽지 않은 문제들이 섞여 있었지만, JavaScript에는 다른 언어에서 볼 수 없는 기특한 메서드가 참 많았다. 길게 풀어야 할 로직을 한 줄로 줄여주는 메서드들을 보며 확실히 아는게 힘이다 라는걸 느꼈다

Lv.0을 끝냈으니 이제 Lv.1을 차근차근 풀어볼 예정이다. 조금 풀어 보니까 Lv.0에서 기초를 탄탄히 다졌다면 Lv.1도 큰 어려움은 없을 것 같다!

참고로 초반에는 기초와 입문 난이도가 비슷하지만, 입문 후반으로 갈수록 어려워진다. 기초와 입문을 따로 진행할 생각이라면 기초 → 입문 순서로 공부하는 것을 추천한다.

마크다운 참고하기 🍪🍄‍🟫☕​

👋 안녕하세요 🤎🧸📜​

제목 4 🌕🍞🍂​

🍩🐿️🍦

1. alert​

2. 텍스트 스타일​

굵게
기울임
취소선
굵고 기울임

3. 목록​

순서 없는 목록​

• 아이템 1
• 아이템 2
  • 하위 아이템

순서 있는 목록​

1. 첫 번째
2. 두 번째
   1. 하위 첫 번째

5. 코드​

console.log("JavaScript 코드 블록");

6. 인용문​

인용문입니다.

중첩 인용문입니다.

8. 체크박스 (GFM)​

• 완료
• 미완료

10. 각주​

문장 안에서 각주를 달 수 있습니다¹.

12. 형광펜​

기본 형광펜이잖아~

14. 코드 블록​

function hello() {
  console.log("2번 줄 하이라이트");
}
console.log("4번 줄 하이라이트");
console.log("4번 줄 하이라이트");
console.log("4번 줄 하이라이트");

import React from 'react';
import Layout from '@theme/Layout';

export default function MyReactPage() {
  return (
    <Layout>
      <h1>My React page</h1>
      <p>This is a React page</p>
    </Layout>
  );
}

console.log("Markdown features including the code block are available");