앱 설정

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

routes

도메인

mobile

앱 정보

env/

환경별 값

images

이미지 규칙

publicEnv

브라우저 환경변수

secrets

시크릿 파일

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: 네이티브 앱 표시 이름입니다. mobile root에서는 모든 target의 기본값이 되고, target 내부에서는 해당 패키지 표시 이름을 override합니다.

appId: com.example.app 같은 네이티브 패키지 식별자입니다. Android는 applicationId/package name으로, iOS는 bundle id로 사용합니다. Firebase Android/iOS 앱 등록도 같은 값을 써야 합니다.

version: 사용자에게 보이는 네이티브 앱 버전입니다. Android versionName과 iOS MARKETING_VERSION에 반영됩니다. target 값은 mobile root 값을 override합니다.

buildNum: 스토어 제출용 빌드 번호입니다. Android versionCode와 iOS CURRENT_PROJECT_VERSION에 반영됩니다. 네이티브 스토어 릴리즈마다 증가시키세요.

targets: 하나의 Akan 앱에서 만드는 이름 있는 모바일 패키지들입니다. 각 target은 basePath, fallback indexPath, 앱 식별 정보 override, permissions, files, assets, deepLinks를 가질 수 있습니다.

target.basePath: 이 네이티브 패키지가 여는 client/basePath입니다. 하나의 Akan 앱에서 고객/관리자/파트너 모바일 앱을 나눌 때 사용합니다. 설정된 route basePath와 맞아야 합니다.

target.indexPath: target의 초기 또는 fallback CSR path입니다. 모바일 시작 경로, 딥링크 stack 복원, back 버튼 fallback에 사용합니다.

target.permissions: devkit이 사용하는 네이티브 권한 힌트입니다. 지원 값은 camera, contacts, location, push입니다. 네이티브에서 usePushNotification을 쓰려면 push를 선언하세요.

target.assets: 앱 루트 기준의 선택적 앱 아이콘/splash 이미지 source path입니다. 네이티브 패키지 브랜딩이 필요할 때 icon과 splash를 사용합니다.

target.files: 네이티브 파일 복사 매핑입니다. key는 생성된 네이티브 프로젝트의 대상 경로이고 value는 앱 기준 source path입니다. google-services.json, GoogleService-Info.plist 같은 네이티브 설정 파일에 사용합니다.

deepLinks: 모바일 target에 사용할 네이티브 URL scheme과 검증된 HTTPS 앱 링크입니다. iOS app link에는 teamId가 필요하고, Android app link에는 릴리즈 검증용 SHA-256 인증서 fingerprint가 필요합니다.

deepLinks.schemes: example:// 같은 커스텀 URL scheme입니다. 단순한 소문자 앱 scheme을 사용하고 다른 앱이 소유한 scheme은 피하세요.

deepLinks.domains: HTTPS app link/universal link 도메인입니다. Akan이 association file을 서빙할 수 있지만, iOS에는 teamId가 필요하고 Android 릴리즈 검증에는 SHA-256 fingerprint가 필요합니다.

deepLinks.ios.teamId: apple-app-site-association에 사용하는 Apple Developer Team ID입니다. 실제 iOS 앱의 universal link에 필요합니다.

deepLinks.android.sha256CertFingerprints: assetlinks.json에 사용하는 서명 인증서 SHA-256 fingerprint입니다. 로컬 테스트에는 debug fingerprint, Play Store 빌드에는 release fingerprint를 사용하세요.

mobile.plugins / android / ios: Capacitor config로 그대로 전달되는 필드입니다. Akan의 상위 설정으로 표현되지 않는 네이티브 플러그인 설정이 필요할 때만 사용하세요.

mobile target files

files는 네이티브 target path를 앱 기준 source file에 매핑합니다. google-services.json, GoogleService-Info.plist 같은 Firebase push 설정 파일에 유용합니다. 서버 service account JSON은 client/native file mapping에 넣지 마세요. 플랫폼별 설정 절차는 모바일 개발 문서를 참고하세요.

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

이미지와 공개 환경변수

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

images

publicEnv

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

시크릿 파일

service-account JSON, TLS 인증서, private key 파일처럼 env.server.*.ts 안에 담을 수 없는 비공개 값이 있습니다. secrets 필드는 이런 파일의 glob 패턴을 나열해 Akan이 env/ 폴더와 함께 전송하도록 합니다.

akan upload-env는 매칭된 모든 파일을 아카이브하고, akan download-env는 이를 복원합니다. 패턴은 앱 디렉터리 기준으로 resolve되며, Akan이 root .gitignore의 managed block에 동기화하므로 한 번의 선언으로 배포와 git-ignore가 함께 처리됩니다.

secrets

.gitignore (auto-synced on upload-env)

publicEnv는 변수 이름을 브라우저에 노출하지만, secrets는 그 반대입니다. config에는 glob 패턴만 존재하며, 매칭된 파일은 로컬에 남고 git-ignore되므로 내용을 절대 commit하지 마세요.

빌드와 런타임

일부 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을 추가하고, 기본 빌드로 부족할 때만 고급 빌드 옵션을 추가하세요.