Akan Config Overview

akan.config.ts is the app or library configuration entry point. Akan uses it to prepare server, web, mobile app, database, build, image, and environment behavior.

You can start with an empty config. Akan treats the file as partial settings and fills missing fields with framework defaults.

apps/myapp/akan.config.ts

Config File Shape

AppConfig and LibConfig can be plain objects or functions. Use a plain object for most cases. Use a function when the config needs the app or library metadata while it is being loaded.

object config

function config

routes

routes connects domains and basePath values to one app. Use it when one Akan app needs to serve several brands, services, or entry paths.

Akan normalizes basePath values, collects domains, adds branch names, and creates default development domains when no explicit domain is provided.

apps/shop/akan.config.ts

If mobile targets use basePath, define that basePath in routes first. Akan validates mobile target basePath values against the route list.

mobile

mobile defines the native app identity and target-specific packaging settings used when a web surface is shipped through Capacitor.

Missing values fall back to app name, com.<app>.app, version 0.0.1, build number 1, and a default target. Target basePath must exist in routes.

apps/shop/akan.config.ts

Keep local keystore paths and private signing values out of shared examples. Put machine-specific values in local-only files or deployment secrets.

defaultDatabaseMode

defaultDatabaseMode chooses the app's default database operating model. Most apps can leave it empty and use the single database default.

Akan stores the resolved mode in the app scan result so database-related commands and runtime setup can share the same default.

apps/enterprise/akan.config.ts

Only customize this when your deployment model really needs separated or clustered database behavior. For details, see Database Mode.

images

images configures Akan's optimized image pipeline. It controls allowed image sizes, output formats, remote sources, local paths, redirects, timeout, and byte limits.

Akan merges your image config with defaults. List fields such as deviceSizes, imageSizes, formats, remotePatterns, and localPatterns keep defaults unless you replace them.

apps/catalog/akan.config.ts

i18n

i18n defines the locales your app supports and the default locale used when no user preference is resolved.

Akan writes the resolved default locale and locale list to AKAN_PUBLIC_DEFAULT_LOCALE and AKAN_PUBLIC_LOCALES for build/runtime use.

apps/global/akan.config.ts

Keep i18n here for app-level language availability. Put actual translated copy in the page, dictionary, or localization layer that owns the text.

publicEnv

publicEnv lists environment keys that are allowed to be exposed to browser code. Treat it as an allowlist for public-safe values.

Akan keeps the list in resolved app config so build and runtime code know which env values may cross the server-to-browser boundary.

apps/landing/akan.config.ts

Never include secrets, database URLs, private tokens, or server credentials in publicEnv.

externalLibs

externalLibs marks dependencies that should not be bundled into app code. When declared here, Akan installs them as separate packages during the production build.

Akan includes externalLibs in the production package dependencies together with required SSR and native runtime packages.

apps/media/akan.config.ts

Use this for native or runtime-sensitive packages. Normal TypeScript helpers usually do not need externalLibs.

barrelImports

barrelImports adds import roots that should be treated as barrel folders. Akan already includes framework barrels and the standard barrel folders from each app and library.

Akan starts with framework defaults such as akanjs/webkit, akanjs/common, akanjs/ui, akanjs/client, and akanjs/server. It also adds @apps/<app>/{ui,webkit,common,client,server} and the same folders from every used @libs/<lib>. Your custom entries are appended after those defaults.

apps/admin/akan.config.ts

Most ui, webkit, common, client, and server folders are already covered. Add this only for a custom barrel outside the standard facets.

optimizeImports

optimizeImports tells Akan which packages or barrels should participate in optimized import handling so pages load only what they use. Akan already includes common UI, icon, chart, hook, and utility packages by default.

Akan merges your entries with default optimized packages such as lucide-react, date-fns, lodash-es, ramda, antd, ahooks, Heroicons, MUI, Recharts, react-use, Tabler icons, and react-icons/*, then removes duplicates.

apps/dashboard/akan.config.ts

Pair this with a clean barrel shape. One file per export makes optimized imports easier to reason about.

docker

docker customizes the production container Akan generates for an app. Use it only when deployment needs extra system packages or a different startup command.

Akan builds Dockerfile content from the base image, default system packages, your run scripts, app env values, base paths, locale values, and command.

apps/worker/akan.config.ts

apps/custom-runtime/akan.config.ts

docker.content is useful when the deployment image must be fully controlled. Keep the default Dockerfile flow when possible: install runtime packages, install production dependencies, copy app files, set Akan public env values, then define CMD.

Library Config Fields

LibConfig uses the same partial object or function shape, but its current practical surface is externalLibs. Use it when a shared library wraps a dependency that must be available in production runtime packaging.

Akan resolves missing values to an empty list and stores the result with the library scan result.

libs/shared/akan.config.ts