시작하기

이 가이드는 빈 디렉터리에서 실행 중인 Akan 애플리케이션까지 안내합니다.

그 과정에서 Akan 방식도 함께 보게 됩니다. 비즈니스 의도를 한 번 설명하면 컨벤션이 page, API, service, store, data, deployment surface를 연결합니다.

Akan.js는 monorepo 구조를 기본으로 합니다. 앱 실행부터 production build, library 개발, package 관리까지 모두 workspace root에서 실행하고 운영합니다.

이 가이드를 읽고 나면 workspace 생성, local runtime 실행, 엔트리 파일을 확인, production build까지 알 수 있습니다.

요구사항

첫 실행에는 Bun만 있으면 됩니다. Docker와 네이티브 IDE는 로컬 서비스나 모바일 빌드를 추가할 때 필요해집니다.

Bun 1.3.13 이상

로컬 데이터 서비스 실행을 위한 Docker

네이티브 앱 빌드를 위한 Android Studio 또는 Xcode

workspace creator로 시작하세요. 몇 가지 질문에 답하면 Akan이 app, library, page, domain module에 사용하는 모노레포 컨벤션을 구성합니다.

터미널 명령어를 복사할 때는 앞의 프롬프트 기호를 제외하고 실행하세요.

Terminal

전역 설치된 CLI를 선호한다면 같은 작업 흐름을 akan 명령으로 사용할 수 있습니다.

Terminal

하나의 명령으로 local Akan runtime을 시작합니다. 워크스페이스를 스캔하고, 컨벤션을 읽고, 생성 산출물을 준비한 뒤 앱을 엽니다.

Terminal

local gateway는 기본적으로 http://localhost:8282 에서 실행됩니다. page, API call, WebSocket traffic, generated asset이 모두 이 runtime을 통해 흐릅니다.

이제 앱은 Akan gateway를 통해 실행됩니다. 페이지를 수정하면 같은 워크스페이스에서 web, app-oriented client surface, API traffic, realtime traffic, generated asset을 함께 제공합니다.

페이지 수정하기

Akan page는 apps/<app>/page 아래에 위치합니다. index page는 _index.tsx 컨벤션을 사용하므로 myapp의 첫 화면은 apps/myapp/page/_index.tsx입니다.

컴포넌트를 수정한 뒤 local gateway를 새로고침해 첫 UI 변경을 확인하세요.

apps/myapp/page/_index.tsx

http://localhost:8282 를 열어 Akan gateway를 통해 페이지를 확인합니다.

Akan runtime은 생성하는 surface에 같은 page 컨벤션을 사용합니다. 따라서 분리된 client project를 따로 유지하지 않고 하나의 page tree에서 작업합니다.

Hello Akan.js! 🎉

앱 엔트리 이해하기

생성된 main.ts는 Akan runtime을 시작합니다. 대부분의 애플리케이션 작업은 page와 domain module에서 이루어지므로 이 파일을 자주 수정할 필요는 없습니다.

apps/myapp/main.ts

akan start가 실행 중이면 터미널에서 local runtime 상태를 확인할 수 있습니다. page와 generated runtime surface는 gateway URL에서 확인합니다.

Terminal

앱을 배포할 준비가 되면 같은 컨벤션으로 빌드합니다. Akan은 production에 필요한 server artifact, route manifest, client entry, static asset, package metadata를 생성합니다.

Terminal

dist/apps/myapp 디렉터리에 production build 결과가 생성됩니다.