App configuration

Your app is configured by a single waid.config.json at the project root (created by waid new). It sets your app's name, icon, store identity, and the device capabilities it needs.

Conventions

Only name (and dist for a real build) is required: everything else is optional with a sensible default.
Keys accept camelCase or snake_case (packageName == package_name).
Unknown keys produce a warning and have no effect, so check spelling and CLI output.
Invalid values (bad icon color, orientation, package name, deeplink scheme) fail the build loudly.

For an older configuration, run waid migrate-config --src . and review the changes. Legacy build-profile keys still parse for compatibility; new projects use the current scaffolded configuration.

Minimal#

json

{
  "name": "my-app",
  "dist": "dist"
}

Basics#

Key	Type	Default	What it does
`name`	string	required	Your app's name, the home-screen label default and the base for derived ids.
`dist`	string	inferred	Path to the built web bundle. Usually inferred from your Vite config.
`version`	string	`1.0.0+1`	App version as `<name>+<build>` (see Version); mapped to the native version fields on every platform.
`icon`	string	bundled default	Path to an SVG app icon. A missing or non-`.svg` path fails the build.
`iconBackground`	`#RRGGBB`	white	Background for the Android adaptive icon.
`orientation`	string	unlocked	Lock the app orientation (`portrait`, `landscape`, …).
Development port	CLI option	project-derived	Use `waid dev --port <port>`; HMR uses Vite’s own connection.

Store identity#

Set your app's store identity per platform. These are optional, since WAID derives a default from name, but you'll want real reverse-DNS ids before shipping.

json

{
  "name": "wildlife-journal",
  "dist": "dist",
  "androidBuildProfile": {
    "packageName": "com.acme.wildlife",
    "appName": "Wildlife Journal"
  },
  "iosBuildProfile": {
    "bundleId": "com.acme.wildlife",
    "appName": "Wildlife Journal"
  }
}

Key	Platform	What it is
`androidBuildProfile.packageName`	Android	The Play Store / install id (`applicationId`). Reverse-DNS, no hyphens.
`androidBuildProfile.appName`	Android	Home-screen label.
`iosBuildProfile.bundleId`	iOS	The App Store / install id. Reverse-DNS.
`iosBuildProfile.appName`	iOS	Home-screen display name.

Signing keys also live in these profiles. See Android release and iOS builds.

Version#

Your app's version is a single Flutter-style string at the top level of waid.config.json, "<name>+<build>", that WAID maps to the native version fields on every platform. Set it once:

json

{
  "name": "wildlife-journal",
  "dist": "dist",
  "version": "1.2.0+7"
}

Part	Android	iOS
name (`1.2.0`)	`versionName`	`CFBundleShortVersionString`
build (`7`)	`versionCode`	`CFBundleVersion`

Absent → "1.0.0+1". Bump the build number on every store upload: both stores reject a build whose number isn't higher than the last. A build profile can override either part for one platform only (androidBuildProfile.versionCode/versionName, iosBuildProfile.version + build number). See Android release and iOS builds.

Renaming is data-safe: except `name`#

WAID keeps your app's stored data and permissions tied to your name, not to the store id. So:

✅ Changing packageName / bundleId is safe: an installed app keeps its data and granted permissions.
⚠️ Do not change name on a shipped app: that orphans its stored data/permissions.
⚠️ Keep name unique across your apps: two apps with the same name share the same storage/permission scope.

Next: Capabilities, the device features your app can request.

App configuration

Minimal#

Basics#

Store identity#

Version#

Renaming is data-safe: except name#

Renaming is data-safe: except `name`#