image
Akan.js
한국어
문서컨벤션레퍼런스Cheatsheet
image
Akan.js
Akan.js v2 문서가 새로 나왔습니다.v1 문서 보기
문서컨벤션레퍼런스Cheatsheet
MIT 라이선스 하에 배포되었습니다.
Akan.js 공식 컨설팅 서비스Akansoft
Copyright © 2026 Akan.js 모든 권리 보유.
시스템 관리자bassman
소개
• 시작하기
• 기본 개념
• 실습하기
튜토리얼
• 상세하게 보여주기
• 상태 변경하기
• 서비스 내에서 상호작용
• 슬라이스로 표시하기
• 페이지를 통한 UX
• 스칼라 사용하기
• 인사이트 사용하기
• 데이터 연결하기
핵심 개념
• Akan 런타임
• 파일 기반 라우팅
• 다중 클라이언트
• 앱 설정
• 폴더 규칙
• 파일 규칙
• 데이터 레이어
시스템 아키텍처
• 아키텍처 개요
• 런타임과 인프라
• UI 아키텍처
• 비즈니스 서비스
• 모바일 앱 아키텍처
• CSS와 스타일링
소개
• 시작하기
• 기본 개념
• 실습하기
튜토리얼
• 상세하게 보여주기
• 상태 변경하기
• 서비스 내에서 상호작용
• 슬라이스로 표시하기
• 페이지를 통한 UX
• 스칼라 사용하기
• 인사이트 사용하기
• 데이터 연결하기
핵심 개념
• Akan 런타임
• 파일 기반 라우팅
• 다중 클라이언트
• 앱 설정
• 폴더 규칙
• 파일 규칙
• 데이터 레이어
시스템 아키텍처
• 아키텍처 개요
• 런타임과 인프라
• UI 아키텍처
• 비즈니스 서비스
• 모바일 앱 아키텍처
• CSS와 스타일링
이전
파일 기반 라우팅
다음
앱 설정

다중 클라이언트

Akan은 basePath로 페이지를 나누어 하나의 앱에서 여러 웹 클라이언트를 제공할 수 있습니다. 로컬 개발에서는 각 클라이언트가 첫 번째 경로 세그먼트로 구분되지만, 배포 후에는 연결된 도메인이 그 세그먼트를 숨기고 별도의 사이트처럼 제공합니다.
One app, many clients
멀티 웹: 각 basePath가 하나의 독립 웹사이트처럼 동작할 수 있습니다.
단일 백엔드: 모든 클라이언트는 같은 앱 서버, 도메인 모듈, 서비스를 공유합니다.
분리된 빌드: CSR 웹과 모바일 앱은 basePath별로 준비될 수 있습니다.

라우트 설정

akan.config.ts의 routes에서 클라이언트를 정의합니다. basePath는 클라이언트 이름이 되고, domains는 배포 환경에서 어떤 도메인이 그 클라이언트를 열지 결정합니다.
apps/myapp/akan.config.ts
basePath
첫 번째 page 폴더이자 클라이언트의 경계입니다. basePath가 store이면 page/store 아래에 페이지를 둡니다.
domains
이 basePath를 열 배포 도메인입니다. 도메인이 매칭되면 사용자는 basePath 세그먼트 없이 사이트를 보게 됩니다.

언제 나눌까

하나의 앱에서 여러 클라이언트 화면을 별도로 운영해야 할 때 basePath를 사용합니다. 코드베이스와 백엔드는 하나로 유지하면서, 각 클라이언트는 별도의 도메인, 진입 페이지, 빌드 결과물, 앱 패키지를 가질 수 있습니다.
basePath를 쓰는 경우
같은 도메인 로직과 백엔드 서비스를 공유하더라도, 제품이나 배포 단위, 접근 대상이 분리되어야 하는 화면에 사용합니다.
일반 라우팅을 쓰는 경우
계정 설정, 대시보드, 탭 화면, 그룹 화면처럼 같은 클라이언트 안에 속한 페이지에는 일반 라우팅을 사용합니다.
고객 사이트와 관리자: 스토어 사이트와 관리자 콘솔은 상품, 주문, 사용자, 권한을 공유하는 경우가 많습니다. 하지만 도메인, 화면 구성, 배포 대상이 다르다면 basePath로 나누는 것이 좋습니다.
고객군이 다른 서비스: 예를 들어 일반 고객용 화면, 파트너 포털, 내부 운영 도구는 같은 백엔드를 사용하면서도 서로 다른 홈 화면과 내비게이션을 가질 수 있습니다.
별도 모바일 앱: 브랜드, 지역, 사용자 유형별로 Android와 iOS 앱을 따로 출시해야 한다면 각 모바일 target이 서로 다른 basePath를 바라보게 할 수 있습니다.
화이트라벨 또는 지역 사이트: 여러 사이트가 같은 비즈니스 규칙을 공유하지만 도메인, 이름, 첫 화면이 달라야 한다면 basePath로 앱을 여러 개 만들지 않고 분리할 수 있습니다.

페이지 구조

routes에 basePath가 있으면 모든 page 파일은 반드시 그 첫 번째 폴더 중 하나 아래에 있어야 합니다. page/ 바로 아래에 있는 페이지는 어떤 클라이언트에 속하는지 결정할 수 없으므로 유효하지 않습니다.
page/
로컬 개발에서는 /store, /admin처럼 basePath로 각 클라이언트를 엽니다. 배포 후에는 설정된 도메인이 같은 클라이언트를 basePath 없이 열 수 있습니다.
규칙: basePath가 선언되면 page/basePath/ 밖에 페이지를 둘 수 없습니다. Akan은 이런 페이지를 라우팅하지 않고 에러를 발생시킵니다.

로컬과 배포

같은 앱이라도 실행 위치에 따라 보이는 방식이 달라집니다. 로컬에서는 하나의 웹 서버 안에서 여러 클라이언트를 오갈 수 있도록 basePath가 보입니다. 배포 환경에서는 도메인이 각 클라이언트로 바로 연결될 수 있습니다.
로컬 개발
배포 도메인

CSR와 모바일 빌드

앱을 빌드하면 Akan은 basePath별 CSR 웹 결과물을 준비할 수 있습니다. 모바일 target도 basePath를 바라볼 수 있으므로, Android와 iOS 앱이 같은 백엔드를 사용하면서 고객군별 클라이언트를 열 수 있습니다.
Build outputs
Mobile targets
핵심은 여러 웹과 여러 앱 클라이언트를 동시에 제공하더라도, Akan 앱과 서버 런타임, 백엔드 도메인 모델은 하나로 유지할 수 있다는 점입니다.
다중 클라이언트
라우트 설정
언제 나눌까
페이지 구조
로컬과 배포
CSR와 모바일 빌드