앱 설정

akan.config.ts는 앱 단위 설정 파일입니다. 처음부터 모든 옵션을 이해할 필요는 없습니다. 빈 파일로 시작하고, 앱에 필요한 필드만 하나씩 추가하면 됩니다.

routes

도메인

mobile

앱 정보

env/

환경별 값

images

이미지 규칙

publicEnv

브라우저 환경변수

advanced

빌드 옵션

작게 시작: 대부분의 기본값은 준비되어 있으므로 빈 config도 유효합니다.

필요한 것만 추가: 앱에서 실제로 바꿔야 하는 부분만 선언하면 됩니다.

하나의 기준점: CLI 명령, 프로덕션 빌드, 모바일 명령이 모두 이 파일을 기준으로 동작합니다.

apps/minimal/akan.config.ts

설정 파일 형태

default export는 일반 객체이거나 함수일 수 있습니다. 대부분의 앱은 객체로 충분합니다. config를 읽는 시점에 앱 메타데이터가 필요할 때만 함수를 사용합니다.

객체 설정

함수 설정

Akan은 config를 부분 설정으로 다룹니다. 선언하지 않은 값은 프레임워크 기본값으로 채워집니다.

애플리케이션 환경설정

akan.config.ts가 앱을 어떻게 빌드하고 라우팅할지 설명한다면, env/ 폴더는 앱이 실행 중 사용할 실제 값을 설명합니다. 공개 가능한 클라이언트 키, 서버 전용 옵션, 환경별 서비스 설정 같은 값이 여기에 들어갑니다.

env/env.client.local.ts

env/env.server.local.ts

env.client.*: 브라우저나 클라이언트 코드에서 사용하는 값입니다. 지도 키, 사이트 키, 기능 스위치처럼 공개되어도 되는 값만 둡니다.

env.server.*: 서버 모듈에서만 사용하는 값입니다. 서버 옵션, 연결 설정, 비공개 서비스 설정을 여기에 둡니다.

local·testing·debug·develop·main: 각 suffix는 AKAN_PUBLIC_ENV 값으로 선택됩니다. local은 내 PC, testing은 테스트, debug/develop은 공유 개발 단계, main은 운영 환경에 사용합니다.

env.*.type.ts: type 파일은 env 값의 형태를 정의합니다. 필요한 값이 빠지거나 이름이 틀린 설정을 코딩 중에 잡을 수 있습니다.

client env와 publicEnv는 다릅니다. env.client.*는 환경별 앱 값을 저장하고, publicEnv는 process.env 중 어떤 이름을 브라우저 빌드에 노출할지 허용하는 목록입니다.

server env는 env.server.type.ts를 통해 shared library의 옵션을 함께 포함할 수 있습니다. 덕분에 앱은 라이브러리 기본값을 재사용하면서 최종 서버 env 객체 하나를 유지할 수 있습니다.

Route와 Domain

routes는 앱에서 사용할 공개 도메인을 적는 곳입니다. 앱에 여러 클라이언트가 있다면 각 route에 basePath로 클라이언트 이름도 적을 수 있습니다. 다중 클라이언트 구조 자체는 Multi Client 페이지에서 자세히 다루고, 여기서는 설정 필드에 집중합니다.

apps/myapp/akan.config.ts

basePath

이 route가 열 클라이언트 이름입니다. Akan은 /store/처럼 적은 값을 store로 정리합니다.

domains

환경 이름별 도메인 목록입니다. debug, develop, main은 기본으로 있고, qa 같은 커스텀 브랜치도 추가할 수 있습니다.

basePath를 선언했다면 page 폴더도 같은 이름을 따라야 합니다. 자세한 page 배치 규칙은 Multi Client 페이지를 참고하세요.

모바일 메타데이터

mobile은 Android와 iOS 명령에서 사용할 네이티브 앱 정보를 설명합니다. 네이티브 앱 프로젝트에 들어갈 이름, 패키지 ID, 버전 정보를 적는 곳이라고 생각하면 됩니다.

Mobile config

appName: 네이티브 앱에 사용할 표시 이름입니다. 기본값은 Akan 앱 이름입니다.

appId: com.example.app 같은 네이티브 패키지 식별자입니다. 기본값은 com.<appName>.app입니다.

version: 사용자에게 보이는 앱 버전입니다. 기본값은 0.0.1입니다.

buildNum: 스토어 제출용 빌드 번호입니다. 기본값은 1이고, 보통 릴리스마다 증가시킵니다.

다중 클라이언트 앱에서 클라이언트별 모바일 앱이 필요하다면 basePath가 있는 mobile target을 정의합니다. 이 패턴은 Multi Client 페이지에서 다룹니다.

이미지와 공개 환경변수

images는 최적화할 수 있는 원격 이미지의 허용 목록을 정합니다. publicEnv는 기본 AKAN_PUBLIC_* 패턴 외에 브라우저에 노출할 환경변수 패턴을 추가하는 허용 목록입니다.

images

publicEnv

publicEnv는 값을 저장하는 곳이 아닙니다. 어떤 환경변수 이름을 브라우저 빌드에 노출해도 되는지 정하는 목록입니다.

빌드와 런타임

일부 config 필드는 주로 빌드 시스템과 프로덕션 런타임을 위한 설정입니다. 대부분의 앱은 건드릴 필요가 없지만, 특정 패키지를 런타임 의존성으로 유지하거나 import 최적화, Docker 이미지 커스터마이징이 필요할 때 사용합니다.

Build and runtime fields

externalLibs: 번들에만 포함하지 않고 프로덕션 런타임 의존성으로 유지할 패키지입니다.

optimizeImports: 클라이언트 빌드에서 import 최적화를 적용할 추가 패키지입니다.

barrelImports: 스캔과 번들링 중 Akan이 펼쳐서 처리할 barrel import 경로입니다.

defaultDatabaseMode: 환경변수 AKAN_DATABASE_MODE가 주어지지 않은 명령에서 사용할 기본 데이터베이스 모드입니다.

기본값과 규칙

Akan은 사용자가 작성한 파일과 프레임워크 기본값을 합쳐 최종 앱 설정을 만듭니다. 처음 앱을 만들 때는 고급 옵션을 추가하기 전에 아래 규칙만 기억하면 됩니다.

환경별 값: config 필드를 추가하기 전에 런타임 값은 env/에 둡니다. 공개 값은 client env에, 서버 전용 비공개 옵션은 server env에 둡니다.

라우트: 커스텀 도메인이나 여러 클라이언트가 필요해지기 전까지는 routes를 생략해도 됩니다.

모바일: appName은 앱 이름, appId는 com.appName.app, version은 0.0.1, buildNum은 1이 기본값입니다.

이미지: remotePatterns가 허용하지 않은 원격 이미지는 차단됩니다. 기본 포맷은 WebP이고 기본 quality는 75입니다.

다국어: 기본 locale 동작을 바꿔야 할 때만 i18n을 설정하면 됩니다.

추천 순서: 빈 config로 시작하고, 앱에 필요한 env/ 값을 채운 뒤, 도메인이 필요할 때 routes를 추가하고, 네이티브 앱이 필요할 때 mobile을 추가하고, 기본 빌드로 부족할 때만 고급 빌드 옵션을 추가하세요.