언제 나눌까
앱에 두 번째 사용자층이 생겼습니다. 스토어와 관리자 콘솔은 서로 다른 도메인, 다른 첫 화면, 때로는 다른 모바일 패키지를 원하지만 상품도 주문도 권한도 같습니다. 앱을 하나 더 만들면 그 전부가 복제됩니다. basePath로 페이지를 나누면 그러지 않아도 됩니다.
기준은 그 화면들이 제품·배포·접근 단위로 나뉘는지입니다. 나뉘면 basePath로 분리하고, 한쪽이 다른 쪽의 구역이라면 route group으로 충분합니다:
상황설명
고객 사이트와 관리자 콘솔
basePath — 상품, 주문, 사용자, 권한을 공유하지만 도메인, 화면 구성, 배포 대상이 다릅니다.일반 고객 화면, 파트너 포털, 내부 운영 도구
basePath — 백엔드는 하나이고 대상은 셋입니다. 앱을 새로 만들지 않고도 각자 홈 화면과 내비게이션을 가집니다.브랜드·지역·사용자 유형별로 따로 출시하는 Android·iOS 패키지
basePath — 네이티브 target이 basePath를 가리키므로, 각 패키지가 같은 백엔드에서 자기 클라이언트를 엽니다.같은 비즈니스 규칙을 쓰는 화이트라벨·지역 사이트
basePath — 같은 도메인 모델 위에 도메인, 이름, 첫 화면만 다릅니다. basePath가 있는 이유가 이것입니다.계정 설정, 대시보드, 탭 화면, 그룹 화면
일반 라우팅 — 하나의 클라이언트 안의 구역입니다. (user) 같은 route group이 URL 세그먼트를 더하지 않고 정리해 줍니다.일부 로그인 사용자만 열 수 있는 구역
일반 라우팅 — 권한은 guard와 layout에서 막는 문제이지 배포 경계가 아닙니다. 이것 때문에 나누면 얻는 것 없이 도메인만 하나 더 씁니다.다중 클라이언트
Akan은 basePath로 페이지를 나누어 하나의 앱에서 여러 웹 클라이언트를 제공할 수 있습니다. 모든 라우트는 locale 아래에 놓이므로, 로컬에서 클라이언트는 locale 바로 다음 세그먼트입니다. 예를 들어 /en/store입니다. 배포 후에는 연결된 도메인이 그 세그먼트를 숨기고 별도의 사이트처럼 제공합니다.
앱 하나, 여러 client
Akan 앱서버 하나, 백엔드 하나
store 웹
admin 웹
partner 웹
demo 웹
store.example.com
admin.example.com
partner.example.com
demo.example.com
멀티 웹: 각 basePath가 하나의 독립 웹사이트처럼 동작할 수 있습니다.
단일 백엔드: 모든 클라이언트는 같은 앱 서버, 도메인 모듈, 서비스를 공유합니다.
분리된 빌드: CSR 웹과 모바일 앱은 basePath별로 준비될 수 있습니다.
라우트 설정
akan.config.ts의 routes에서 클라이언트를 정의합니다. basePath는 클라이언트 이름이 되고, domains는 배포 환경에서 어떤 도메인이 그 클라이언트를 열지 결정합니다.
apps/myapp/akan.config.ts
basePathstring
이 route가 여는 클라이언트이자 첫 page 폴더입니다. basePath가 store이면 page/store 아래에 둡니다.
domainsRecord<branch, string[]>기본값 {}
이 basePath를 여는 호스트이며 branch를 키로 씁니다. 매칭된 호스트에서는 basePath 세그먼트가 보이지 않습니다.
페이지 구조
routes에 basePath가 있으면 모든 page 파일은 반드시 그 첫 번째 폴더 중 하나 아래에 있어야 합니다. page/ 바로 아래에 있는 페이지는 어떤 클라이언트에 속하는지 결정할 수 없으므로 유효하지 않습니다.
page/
로컬 개발에서는 locale 다음에 basePath를 붙여 각 클라이언트를 엽니다. /en/store, /ko/admin 같은 형태입니다. 배포 후에는 설정된 도메인이 같은 클라이언트를 basePath 없이 열 수 있습니다.
규칙: basePath가 선언되면 page/basePath/ 밖에 페이지를 둘 수 없습니다.
로컬과 배포
같은 앱이라도 실행 위치에 따라 보이는 방식이 달라집니다. 로컬에서는 하나의 웹 서버 안에서 여러 클라이언트를 오갈 수 있도록 basePath가 보입니다. 배포 환경에서는 도메인이 각 클라이언트로 바로 연결될 수 있습니다.
로컬 개발
배포 도메인
partner는 도메인을 직접 선언하지 않았는데도 도메인을 갖습니다. Akan이 알고 있는 모든 branch에 대해 basePath별로 <basePath>-<branch>.<serveDomain>을 자동으로 만들기 때문입니다. 그래서 partner-main.example.com과 partner-develop.example.com은 적지 않아도 존재합니다.
클라이언트에 연결된 도메인은 그 클라이언트만 엽니다. store.example.com에서 /en/admin/users는 새로고침이든 클라이언트 쪽 이동이든 store 안에서 찾으므로, 다른 클라이언트로는 그 클라이언트의 도메인으로 링크합니다.
로컬에서는 사이트 루트에 해당하는 페이지가 없으므로, Akan이 404 대신 빌드에 포함된 모든 basePath 목록을 보여줍니다. 배포 환경에서는 이 목록이 나타나지 않고 매칭된 도메인이 해당 클라이언트를 바로 엽니다.
CSR와 모바일 빌드
앱을 빌드하면 Akan은 basePath별 CSR 웹 결과물을 준비할 수 있습니다. 네이티브 target도 basePath를 바라볼 수 있으므로, Android와 iOS 앱이 같은 백엔드를 사용하면서 고객군별 클라이언트를 열 수 있습니다.
Native targets
target의 basePath는 routes에 선언된 값이어야 합니다.
핵심은 여러 웹과 여러 앱 클라이언트를 동시에 제공하더라도, Akan 앱과 서버 런타임, 백엔드 도메인 모델은 하나로 유지할 수 있다는 점입니다.