Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

App Configuration with app.json

Configure an Expo app with app.json and dynamic app.config.ts: name, slug, icons, splash, identifiers, plugins, extra values and environment-specific builds.

Every Expo project has one configuration source of truth: app.json, or a script version (app.config.js / app.config.ts) when you need logic. It controls the app name, icon, splash screen, bundle identifiers, orientation, permissions text, config plugins and much more. The CLI, Metro, EAS Build and the native generation step all read it.

The files are read-only in this lesson, and live stand-ins model how dynamic config is evaluated and merged.

A basic app.json

JSON
{
  "expo": {
    "name": "Trail Notes",
    "slug": "trail-notes",
    "version": "1.0.0",
    "scheme": "trailnotes",
    "orientation": "portrait",
    "icon": "./assets/icon.png",
    "userInterfaceStyle": "automatic",
    "ios": {
      "bundleIdentifier": "com.example.trailnotes",
      "supportsTablet": true
    },
    "android": {
      "package": "com.example.trailnotes",
      "adaptiveIcon": {
        "foregroundImage": "./assets/adaptive-icon.png",
        "backgroundColor": "#ffffff"
      }
    },
    "web": { "bundler": "metro", "output": "static" },
    "plugins": ["expo-router"]
  }
}

Key fields:

Field Purpose
name display name under the icon
slug URL-safe identifier (used by EAS and updates)
version user-visible version, for example 1.0.0
scheme custom URL scheme for deep links, like trailnotes:// (Links and Deep Links)
icon 1024x1024 PNG without transparency for iOS
userInterfaceStyle light, dark or automatic (Themes and Dark Mode)
ios.bundleIdentifier / android.package the permanent unique app ID, chosen once per store listing
plugins config plugins that edit native projects (Prebuild and Config Plugins)
extra free-form values readable in JavaScript

Choose the bundle identifier and package name carefully. After you publish, changing them creates a different app in the stores.

Reading the config in code

expo-constants exposes the resolved config:

TSX
import Constants from 'expo-constants';

const appName = Constants.expoConfig?.name;
const apiBase = Constants.expoConfig?.extra?.apiUrl;

Do not put secrets in extra: the config is embedded in the app and anyone can read it.

Dynamic configuration: app.config.ts

When you need variants (development, staging, production), create app.config.ts. It exports a function that receives the static app.json as config and returns the final object:

TypeScript
import { ExpoConfig, ConfigContext } from 'expo/config';

const IS_DEV = process.env.APP_VARIANT === 'development';

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: IS_DEV ? 'Trail Notes (Dev)' : 'Trail Notes',
  ios: {
    ...config.ios,
    bundleIdentifier: IS_DEV ? 'com.example.trailnotes.dev' : 'com.example.trailnotes',
  },
  android: {
    ...config.android,
    package: IS_DEV ? 'com.example.trailnotes.dev' : 'com.example.trailnotes',
  },
  extra: {
    apiUrl: process.env.API_URL ?? 'https://api.example.com',
  },
});

Different identifiers let you install the dev and production versions side by side on one phone. If both app.json and app.config.ts exist, app.json is passed in as config.

JS Evaluate a dynamic config

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Environment variables

Expo loads .env files and exposes variables whose names start with EXPO_PUBLIC_ to your app code, inlined at build time:

Terminal
# .env
EXPO_PUBLIC_API_URL=https://api.example.com
TSX
const url = process.env.EXPO_PUBLIC_API_URL;

EXPO_PUBLIC_ values are public; they end up in the bundle. For real secrets (private API keys, signing keys) keep them on a server or in EAS Secrets, never in the app. Variables without the prefix are available only inside app.config.ts and build scripts, not in app code.

Validating a config

Mistakes in the config often appear late (a build fails or the store rejects the app). A small check helps. The stand-in below validates the rules that bite most often.

JS Config validator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Other settings you will meet

  • Splash screen and icons: configured with the expo-splash-screen plugin (image, background color, resize mode).
  • Permissions text: iOS needs a purpose string for camera, location, etc. (set with plugin options such as cameraPermission).
  • newArchEnabled, jsEngine: engine and architecture switches (new projects use sensible defaults).
  • runtimeVersion and updates: control over-the-air updates (EAS Build and Updates).
  • experiments: opt-in features, such as typed routes: "experiments": { "typedRoutes": true }.

After editing the config, restart the dev server. If you changed anything native (identifiers, plugins, permissions), rebuild the development build or run prebuild again.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When do you use app.config.ts instead of app.json?

    app.config.ts is a script that can read process.env and compute values; static values can stay in app.json.
  2. 2. Which environment variables are available in app code?

    EXPO_PUBLIC_ variables are inlined into the bundle. They are not secret.
  3. 3. Why give the development variant a different bundle identifier?

    Two different identifiers are two different apps on the device.
  4. 4. Where should a private API secret be stored?

    Anything shipped in the app can be extracted. Keep secrets server-side.

Summary

  • app.json (or app.config.ts) is the single source of truth for name, icon, identifiers, plugins and more.
  • Dynamic config receives the static config and returns the final one, enabling dev/staging/production variants.
  • EXPO_PUBLIC_ variables are public build-time values; never ship secrets in the app.
  • Native-affecting changes need a rebuild.

Next: Prebuild and Config Plugins