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

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.

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.

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.