앞 페이지에서 백엔드의 첫 골격을 세웠다면, 이제 그 서버와 나란히 움직일 프론트엔드 뼈대를 만들어야 합니다. 이 단계에서 중요한 것은 화면을 예쁘게 만드는 것이 아닙니다. 어떤 앱이 어떤 책임을 가지는지, 어떤 라우트 구조와 레이아웃을 기준으로 커질 것인지, API와 상태를 어디에서 연결할 것인지를 먼저 고정하는 것입니다.
이번 교재의 프론트는 하나의 React 앱으로 모든 것을 해결하지 않습니다. 구매자를 위한 storefront와 운영자를 위한 admin은 같은 제품의 일부이지만, 역할과 접근 권한과 사용자 흐름이 완전히 다릅니다. 따라서 처음부터 별도 앱으로 세우는 것이 맞습니다.
이 페이지의 목적은 storefront와 admin을 "나중에 분리할 예정인 하나의 앱"이 아니라, 처음부터 독립적인 surface로 세우는 것입니다. 이후 장에서 상품 목록, 로그인, 장바구니, 주문, 운영자 대시보드가 들어와도 흔들리지 않도록 골격을 먼저 잡습니다.
백엔드 API가 아직 완성되지 않았다고 해서 프론트 구조를 미뤄도 되는 것은 아닙니다. 오히려 지금처럼 기능이 많지 않을 때 라우트 구조, 레이아웃, provider 위치, API 클라이언트 자리를 먼저 정해야 뒤에서 덜 흔들립니다.
프론트 골격 없이 화면부터 막 만들기 시작하면 보통 아래 문제가 생깁니다.
storefront와 admin이 같은 전역 상태를 억지로 공유한다그래서 이번 교재에서는 기능 구현보다 먼저 앱의 외곽 구조를 고정합니다.
이 페이지를 읽고 나면 아래 항목이 정리되어 있어야 합니다.
storefront와 admin을 분리하는가이번 프로젝트에서 storefront와 admin은 단순히 메뉴가 다른 화면이 아닙니다.
storefront는 탐색, 구매, 주문 확인이 중심이다admin은 운영, 조회, 관리가 중심이다이 둘을 한 앱 안에서 조건문으로 계속 분기하면, 처음에는 쉬워 보여도 곧 유지보수가 어려워집니다. 따라서 이번 교재에서는 client/storefront와 client/admin을 별도 React 앱으로 두고 시작하는 것이 맞습니다.
아직 상품 상세와 주문 결제가 완성되지 않았더라도, 각 앱은 최소한 아래 상태까지는 와 있어야 합니다.
즉 이번 단계의 목표는 "화면이 많은 앱"이 아니라, "기능이 안전하게 추가될 앱 구조"를 만드는 것입니다.
프론트에서도 main.tsx나 앱 진입점 파일이 비대해지면 안 됩니다. 진입점의 역할은 아래 정도면 충분합니다.
진입점 파일이 너무 많은 일을 하면, 인증이나 API 설정이나 레이아웃 로직이 엉키기 쉽습니다. 따라서 이번 교재에서는 진입점은 최대한 얇게 두고, 실제 화면 구조는 app, pages, shared 같은 하위 경계로 분리하는 편이 좋습니다.
storefront는 구매자 중심의 흐름을 담당합니다. 따라서 초기에 아래 라우트 정도가 뼈대로 잡혀 있으면 충분합니다.
이 단계에서는 모든 화면이 완성되어 있을 필요는 없습니다. 중요한 것은 "구매자 여정의 주요 경로가 어디에 놓일지"가 구조로 먼저 드러나는 것입니다.
admin은 운영자 작업이 중심이므로 storefront와 같은 탐색 구조를 쓰면 안 됩니다. 초기에 아래 정도 경로를 두는 것이 자연스럽습니다.
이렇게 분리해두면 이후 장에서 운영자 인증과 보호 라우트를 붙이기가 쉬워집니다.
React 프로젝트에서 흔한 실수 중 하나는 페이지를 먼저 만들고 나중에 공통 레이아웃을 뽑는 것입니다. 이 방식은 초반에는 빠르지만, 헤더, 내비게이션, 컨테이너 폭, 인증 가드가 중복되기 시작하면 빠르게 지저분해집니다.
이번 교재에서는 최소한 아래 레이아웃을 먼저 정하는 것이 좋습니다.
이렇게 하면 나중에 페이지를 추가해도 공통 외곽을 계속 재사용할 수 있습니다.
프론트 골격에서 provider 위치를 먼저 정하지 않으면, 상태와 설정이 화면 곳곳으로 퍼집니다. 이번 교재에서는 아래 정도 provider를 예상할 수 있습니다.
중요한 점은 모든 상태를 전역으로 올리는 것이 아니라, "앱 전체에서 공유해야 하는 것만" provider로 둔다는 것입니다. 예를 들어 장바구니 로컬 표시 상태 같은 것은 전역이 아닐 수도 있지만, 로그인 사용자 정보와 API 클라이언트는 전역에 가깝습니다.
프론트 두 앱을 만들면 곧 공통 코드가 필요해집니다. 하지만 모든 것을 공통으로 빼기 시작하면 오히려 구조가 흐려집니다.
이번 단계에서는 아래 정도만 공통 후보로 보는 것이 적절합니다.
반대로 아래는 너무 이르게 공통화하지 않는 편이 좋습니다.
storefront 전용 구매 흐름 컴포넌트admin 전용 테이블 화면즉 공통화는 재사용이 실제로 두 앱에 동시에 필요한 부분만 대상으로 해야 합니다.
백엔드 기능이 아직 비어 있어도, 프론트는 API를 어디서 부를 것인지부터 정해야 합니다. 그렇지 않으면 컴포넌트마다 fetch를 직접 호출하게 됩니다.
이번 교재에서는 최소한 아래 기준이 필요합니다.
이 자리가 먼저 있어야 이후 장의 카탈로그, 인증, 장바구니 기능을 일관되게 붙일 수 있습니다.
운영자 화면은 특히 첫날부터 보호 라우트를 염두에 둬야 합니다. 아직 실제 인증이 완성되지 않았더라도, 구조는 아래처럼 생각하고 시작해야 합니다.
storefront의 공개 라우트와 인증 필요 라우트를 구분한다admin은 로그인 전과 후의 레이아웃을 구분한다이렇게 해야 나중에 인증 구현이 들어와도 페이지 구조를 갈아엎지 않아도 됩니다.
초기 단계에서 기능이 비어 있어도, 아래 상태는 먼저 다뤄야 합니다.
왜냐하면 이후 장에서 API를 붙이는 순간 이 상태들이 바로 필요해지기 때문입니다. 실제 데이터가 아직 없어도, 화면이 실패를 어떻게 표현할지 자리를 먼저 만들어두는 편이 맞습니다.
정확한 이름은 팀 취향이 조금 반영될 수 있지만, 이번 교재에서는 아래 사고로 시작하는 편이 자연스럽습니다.
client/storefront/src/
app/
pages/
shared/
client/admin/src/
app/
pages/
shared/
여기서 대략 아래 역할을 가집니다.
app: 앱 조립, 라우터, provider, 루트 레이아웃pages: 화면 단위 컴포넌트shared: 공통 UI, 공통 유틸, 공통 훅이 구조는 단순하지만, 뒤 장에서 기능이 늘어날 때 확장하기 쉽습니다.
초기 골격 단계에서 가장 중요한 것은 "무슨 라이브러리를 쓸까"보다 "어떤 상태를 어디에 둘까"입니다.
이번 교재에서는 아래 구분이 중요합니다.
서버 데이터와 UI 상태를 같은 방식으로 다루면 구조가 금방 복잡해집니다. 따라서 처음부터 API 기반 데이터와 로컬 UI 상태를 구분하는 사고를 가져야 합니다.
아직 복잡한 상호작용 테스트까지는 필요 없지만, 최소한 아래 정도는 확인할 수 있어야 합니다.
이 테스트가 있어야 이후 장에서 기능을 붙여도 골격 자체가 깨졌는지 빨리 알 수 있습니다.
이번 페이지를 코드로 옮기면 아래 산출물이 있어야 합니다.
storefront React 앱 초기화admin React 앱 초기화이 산출물이 있어야 다음 페이지에서 백엔드와 프론트가 공유할 API 계약과 타입을 맞추는 작업으로 자연스럽게 넘어갈 수 있습니다.
storefront와 admin을 하나의 앱 안에서 조건문으로 분기한다이 여섯 가지 실수는 카탈로그와 인증이 붙기 시작하면 바로 구조 비용으로 돌아옵니다.
이 페이지에서 우리는 storefront와 admin을 각각 독립적인 React 앱으로 세우고, 라우트, 레이아웃, provider, API 클라이언트 자리를 어떻게 먼저 고정해야 하는지 정리했습니다. 또한 공통 UI와 타입을 어디까지 공유할지, 보호 라우트와 오류 상태를 왜 골격 단계에서부터 고려해야 하는지도 확인했습니다.
다음 페이지에서는 이제 백엔드와 프론트가 실제로 같은 말을 하도록 API 계약과 공통 타입, 인증 바닥을 맞춥니다.