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. Defaults to the Akan app name.

appId: Native package identifier, such as com.example.app. Defaults to com.<appName>.app.

version: User-facing app version. Defaults to 0.0.1.

buildNum: Store build number. Defaults to 1 and is commonly increased for each release.

targets: Per-package mobile settings. A target can select a basePath, indexPath, app identity overrides, permissions, files, and deepLinks.

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.

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

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.