App Configuration

Every app has a small settings file that controls things like the app's name on the home screen, the icon, the splash screen at launch, what permissions the app asks for, and which web links should open in the app.

In React Native apps (which is what Appsanic builds), this file is called app.json. You almost never edit it by hand. You describe what you want to the agent in normal sentences, and it updates the file.

This page is a tour of what lives in there, so you know what's possible.

The app's name

The name that appears under the icon on a user's home screen, and in the App Store/Play Store listing.

"Change the app's name to 'Habit Forge'."

The app's identifier

Every app has a unique identifier. Apple calls it the Bundle ID, Android calls it the package name, but it's the same idea. It's a short, reverse-domain string like com.habitforge.app.

You pick this once. It's permanent. Once your app is live on the App Store with a given Bundle ID, you can't change it. You'd have to publish a new app. Pick something deliberate, ideally based on a domain you own.

Format: lowercase, reverse-dotted: com.yourname.yourappname. See the Glossary entry for Bundle ID.

"Change the iOS bundle identifier to com.habitforge.mobile and the Android package name to the same."

The icon

The thing users see on the home screen 100 times a day. Worth getting right.

Heads-up: if you've set up a brand kit with a logo, the agent uses that automatically as your starter icon.

Apple wants a 1024×1024 PNG with no transparency and no rounded corners (iOS rounds them automatically). Android accepts the same but also supports adaptive icons (a foreground shape on a coloured background) for nicer effects.

To update:

"Use the uploaded image as the app icon. Generate the Android adaptive icon from it too."

You drop the icon into your project and the agent generates every size and format the stores need.

The splash screen

What shows for half a second when the app launches, before the first screen loads.

Design tips:

• Keep it simple. A logo on a solid colour.
• Test in both light and dark mode if your app supports both.
• Don't put text on the splash. It can't be translated cleanly for international users.

"Change the splash screen to a deep navy background with the white version of our logo, centred."

Permissions

Anything the app needs from the user's phone. Camera, location, microphone, photo library. Has to be declared in app.json. When the user does something that needs that thing, the operating system shows them a permission prompt; what the prompt says comes from you.

Apple is strict about this. A vague or missing explanation gets your app rejected at review. Be honest and specific:

"Change the location permission explanation to say 'We only use your location while you're looking for nearby shops, and never share it.'"

The agent writes sensible defaults that match the features you've turned on. Refine as needed.

Deep links. Opening the app from a URL

Lets a URL like myapp://post/123 or https://myapp.com/post/123 open your app to a specific screen. The setting in app.json:

"scheme": "myapp"

See Deep Linking for the full setup.

Orientation

Locks the screen direction:

• "portrait". Locked to upright. Most apps.
• "landscape". Locked sideways. Tablet games, video apps.
• "default". Rotates with the phone. Requires layouts that adapt to both.

Versioning. The two numbers

Two version numbers, both important:

• version (e.g., "1.2.3"). What users see in settings and the store. Friendly, semantic.
• buildNumber (iOS) / versionCode (Android). Internal integers that must always go up on every store submission. The stores reject uploads with non-increasing values.

The agent bumps these automatically on each build. If you're manually building from your exported repo, remember to bump both.

Dark mode

"userInterfaceStyle": "automatic"

Three options:

• "automatic". Match the user's system setting (default).
• "light". Always light.
• "dark". Always dark.

The app.json setting tells the OS what to expect; your UI still needs to actually support dark colours. New projects come with NativeWind (see the Glossary), so dark mode styling uses the standard dark: modifier. Ask:

"Add dark-mode styles to every screen. Match the system appearance."

App Store and Play Store metadata

Some things live in app.json; others live only in the store dashboards.

See Publishing to the App Store and Publishing to Google Play.

Testing config changes

After any change:

1. Restart Appsanic's preview (Preview → Restart server).
2. Reload the app on your phone.
3. Some changes (icon, splash, permissions) only apply to full builds, not Expo Go. Ask the agent to trigger a Dev Client build to verify.

Things that catch people out

• Bundle ID typos. Pick it once, carefully. Write it down somewhere.
• Forgetting to bump versionCode. Android rejects uploads with the same or lower value.
• Permission strings in English only. If you're releasing in multiple languages, localise the explanation strings.
• Splash screen wrong for dark mode. A dark logo on a white splash, then the app loads to dark mode. Looks jarring. Provide a matching dark splash if it matters.

Under the hood (for engineers)

app.json is the static form; app.config.ts is the dynamic form (env-var-driven). Platform-specific fields nest under ios and android. iOS permission strings go in ios.infoPlist (NSCameraUsageDescription, etc.); Android permissions are a string list (CAMERA, ACCESS_FINE_LOCATION).

The agent does the right thing whichever form you're on. Pick app.json until you need env-var-driven config (multi-env builds).

Next

Read Navigation Patterns for tabs, stacks, and modals.