App Config

akan.config.ts is the app-level settings file. You do not need to understand every option on day one. Start with an empty file, then add only the fields your app actually needs.

routes

Domains

mobile

App identity

env/

Env values

images

Image rules

publicEnv

Browser env

secrets

Secret files

advanced

Build options

Start small: Most defaults are already prepared, so an empty config is valid.

Add only what changes: Define only the parts your app actually needs to customize.

One source of truth: CLI commands, production builds, and mobile commands all read this file.

apps/minimal/akan.config.ts

Config Shape

The default export can be a plain object or a function. Use an object for most apps. Use a function only when the config needs app metadata while it is being loaded.

Object config

Function config

Akan treats config as partial settings. Missing fields are filled with framework defaults.

Application Env

akan.config.ts describes how the app is built and routed. The env/ folder describes the actual values the app uses at runtime, such as public client keys, server-only options, and environment-specific service settings.

env/env.client.local.ts

env/env.server.local.ts

env.client.*: Values used by browser or client-side code. Keep only public-safe values here, such as map keys, site keys, or feature switches.

env.server.*: Values used only by server-side modules. Put server options, connection settings, and private service configuration here.

local·testing·debug·develop·main: Each suffix is selected by AKAN_PUBLIC_ENV. Use local for your machine, testing for tests, debug/develop for shared stages, and main for production.

env.*.type.ts: Type files define the shape of env values, so missing or misspelled settings can be caught while coding.

Client env and publicEnv are different. env.client.* stores app values for each environment, while publicEnv only allows selected process.env names to be exposed to browser builds.

Server env can also include options from shared libraries through env.server.type.ts. This lets an app keep one final server env object while reusing library-level defaults.

Routes and Domains

routes is where you list the public domains for the app. If your app has several clients, each route can also name the client with basePath. The multi-client page explains that structure in detail; here we focus on the config fields.

apps/myapp/akan.config.ts

basePath

Optional client name for this route. Akan normalizes /store/ to store.

domains

A map of environment names to domains. debug, develop, and main exist by default, and custom branches such as qa can be added.

If you declare basePath, the page folder must follow the same name. See Multi Client for the full page layout rule.

Mobile Metadata

mobile describes the native app identity used by Android and iOS commands. Think of it as the name, package id, and version information that will appear in native app projects.

Mobile config

appName: Display name used for the native app. At the mobile root it becomes the default for every target; inside a target it overrides the display name for that package.

appId: Native package identifier, such as com.example.app. Android uses it as applicationId/package name and iOS uses it as bundle id. Firebase Android/iOS app registration must use the same value.

version: User-facing native app version, mapped to Android versionName and iOS MARKETING_VERSION. Target value overrides the mobile root value.

buildNum: Store build number, mapped to Android versionCode and iOS CURRENT_PROJECT_VERSION. Increase it for each native store release.

targets: Named mobile packages built from the same Akan app. Each target can select a basePath, fallback indexPath, identity overrides, permissions, files, assets, and deepLinks.

target.basePath: Client/basePath opened by this native package. Use it when one Akan app ships separate customer/admin/partner mobile apps. It should match a configured route basePath.

target.indexPath: Initial or fallback CSR path for the target. Akan uses it for mobile startup, deep link stack recovery, and back-button fallback.

target.permissions: Native permission hints used by devkit. Supported values are camera, contacts, location, and push. Declare push before using usePushNotification on native apps.

target.assets: Optional app icon and splash image source paths, relative to the app root. Use icon and splash when the native package needs custom branding.

target.files: Native file copy map. Keys are generated native project paths and values are app-relative source paths. Use it for google-services.json, GoogleService-Info.plist, or other native config files.

deepLinks: Native URL schemes and verified HTTPS app links for a mobile target. iOS app links require teamId; Android app links require SHA-256 certificate fingerprints for release verification.

deepLinks.schemes: Custom URL schemes such as example://. Use simple lower-case app schemes and avoid schemes owned by other apps.

deepLinks.domains: HTTPS app-link/universal-link domains. Akan can serve association files, but iOS still needs teamId and Android release verification needs SHA-256 fingerprints.

deepLinks.ios.teamId: Apple Developer Team ID used for apple-app-site-association. Required for universal links on real iOS apps.

deepLinks.android.sha256CertFingerprints: Signing certificate SHA-256 fingerprints used by assetlinks.json. Use debug fingerprints for local testing and release fingerprints for Play Store builds.

mobile.plugins / android / ios: Passthrough Capacitor config fields. Use them only when a Capacitor plugin requires native configuration not covered by Akan's higher-level fields.

mobile target files

files maps native target paths to app-relative source files. It is useful for Firebase push config files such as google-services.json and GoogleService-Info.plist. Keep server service account JSON out of client/native file mappings. For platform setup steps, see Mobile Development.

When a multi-client app needs separate mobile apps per client, define mobile targets with basePath. The Multi Client page shows that pattern.

Images And Public Env

images controls the allow-list for optimized remote images. publicEnv is an allow-list for extra browser-visible environment variables beyond the built-in AKAN_PUBLIC_* pattern.

images

publicEnv

publicEnv does not store values. It only says which environment variable names are safe to expose to browser builds.

Secret Files

Some private values cannot live inside env.server.*.ts, such as service-account JSON, TLS certificates, or private key files. The secrets field lists glob patterns for these files so Akan ships them together with the env/ folder.

akan upload-env archives every matched file, and akan download-env restores them. Patterns are resolved relative to the app directory, and Akan syncs them into a managed block in the root .gitignore, so one declaration both deploys and git-ignores the files.

secrets

.gitignore (auto-synced on upload-env)

publicEnv exposes variable names to the browser; secrets does the opposite. Only glob patterns live in config — the matched files stay local and git-ignored, so never commit their contents.

Build And Runtime

Some config fields are mainly for the build system and production runtime. Most apps do not need to touch them, but they are useful when a package must stay external, imports need optimization, or the Docker image needs customization.

Build and runtime fields

externalLibs: Packages kept as production runtime dependencies instead of only being bundled.

optimizeImports: Extra packages whose imports should be optimized by the client build.

barrelImports: Barrel import paths that Akan can flatten while scanning and bundling.

defaultDatabaseMode: Fallback database mode for commands that do not receive AKAN_DATABASE_MODE from the environment.

Defaults And Rules

Akan resolves the final app config by merging your file with framework defaults. For a first app, keep these rules in mind before adding advanced options.

Environment values: Put runtime values in env/ before adding config fields. Use client env for public values and server env for private server options.

Routes: Skip routes until you need custom domains or multiple clients.

Mobile: appName defaults to the app name, appId defaults to com.appName.app, version defaults to 0.0.1, and buildNum defaults to 1.

Images: Remote images are blocked unless remotePatterns allow them. WebP and quality 75 are used by default.

i18n: Only configure i18n when your app needs to change the default locale behavior.

Recommended order: start with an empty config, fill env/ values as the app needs them, add routes when domains are needed, add mobile when native apps are needed, and add advanced build options only after the default build is not enough.