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 as the toolchain sees it: the base for derived ids and the stored-data identity.
`id`	string	derived	Reverse-DNS identity the OS and the stores use on every platform.
`displayName`	string	`name`	The name users see: home screen, dock, app switcher.
`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.
`settings.iconBackground`	`#RRGGBB`	white	Background for the Android adaptive icon.
`settings.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.

One id and one displayName cover every platform:

json

{
  "name": "wildlife-journal",
  "dist": "dist",
  "id": "com.acme.wildlife",
  "displayName": "Wildlife Journal"
}

Add a platform section only where something genuinely differs — an App Store record with a hyphen Android would reject, or a signing team:

json

{
  "name": "wildlife-journal",
  "id": "com.acme.wildlife",
  "displayName": "Wildlife Journal",
  "darwin": {
    "team": "ABCDE12345",
    "ios": { "id": "com.acme.wildlife-journal" }
  }
}

Key	Platform	What it is
`id`	all	The install / store id. Reverse-DNS, no hyphens (the Android rule).
`android.id` · `android.name`	Android	Override the id or home-screen label for Android only.
`android.signing.keystore` · `android.signing.keyAlias`	Android	Release signing.
`darwin.team`	iOS + macOS	Apple Developer team, shared by both.
`darwin.ios.id` · `darwin.ios.name`	iOS	Override the bundle id or display name for iOS only.
`windows` · `linux`	desktop	`id` / `name` / `version` overrides for those hosts.

See Android release and iOS builds.

Older key names. androidBuildProfile and iosBuildProfile still parse, but each prints a deprecation warning on every build. packageName and bundleId collapse into one id; both appNames collapse into one displayName. Run waid migrate-config to perform the rewrite — it leaves name alone, since that is still your project slug.

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 (android.version, darwin.ios.version). 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 id 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`#