File: configuration.md | Updated: 11/15/2025
Hide navigation
Search
Ctrl K
Home Guides EAS Reference Learn
Archive Expo Snack Discord and Forums Newsletter
Copy page
Learn about what app.json/app.config.js/app.config.ts files are and how you can customize and use them dynamically.
Copy page
The app config (app.json, app.config.js, app.config.ts) is used for configuring Expo Prebuild generation, how a project loads in Expo Go , and the OTA update manifest.
It must be located at the root of your project, next to the package.json. Here is a minimal example:
app.json
Copy
{ "name": "My app", "slug": "my-app" }
If your Expo config has a top-level expo: {} object, then this will be used in place of the root object and all other keys will be ignored.
App config schema reference
Explore the full schema of the app config (app.json/app.config.js).
The app config configures many things such as app name, icon, splash screen, deep linking scheme, API keys to use for some services and so on. For a complete list of available properties, see app.json/app.config.js/app.config.ts reference .
Do you use Visual Studio Code? If so, we recommend that you install the Expo Tools extension to get auto-completion of properties in app.json files.
Reading configuration values in your app
Most configuration in the app config is accessible at runtime from your JavaScript code, using Constants.expoConfig
. You should not include any sensitive information in the app config (with a few exceptions for fields that are filtered out, as outlined below).
You can verify which configuration will be embedded in your builds/updates and available at runtime by running npx expo config --type public.
Which fields are filtered out of the public app config?
The following fields are filtered out of the public app config (and not accessible through the Constants.expoConfig object):
You should also avoid importing app.json or app.config.js directly in your JavaScript code, because this will import the entire file rather than a processed version of it. Instead, use
Constants.expoConfigto access the configuration.
Library authors can extend the app config by using Expo Config plugins .
Config plugins are mostly used to configure the
npx expo prebuildcommand.
For more customization, you can use the JavaScript (app.config.js) or TypeScript (app.config.ts). These configs have the following properties:
import keyword) is not supported, except when using TypeScript with tsx
. JS files that are compatible with your current version of Node.js can be imported with require().For example, you can export an object to define your custom config:
app.config.js
Copy
const myValue = 'My App'; module.exports = { name: myValue, version: process.env.MY_CUSTOM_PROJECT_VERSION || '1.0.0', // All values in extra will be passed to your app. extra: { fact: 'kittens are cool', }, };
The "extra" key allows passing arbitrary configuration data to your app. The value of this key is accessed using expo-constants
:
App.js
Copy
import Constants from 'expo-constants'; Constants.expoConfig.extra.fact === 'kittens are cool';
You can access and modify incoming config values by exporting a function that returns an object. This is useful if your project also has an app.json. By default, Expo CLI will read the app.json first and send the normalized results to the app.config.js.
For example, your app.json could look like this:
app.json
Copy
{ "name": "My App" }
And in your app.config.js, you are provided with that configuration in the arguments to the exported function:
app.config.js
Copy
module.exports = ({ config }) => { console.log(config.name); // prints 'My App' return { ...config, }; };
It's common to have some different configuration in development, staging, and production environments, or to swap out configuration entirely to white label an app. To accomplish this, you can use app.config.js along with environment variables.
app.config.js
Copy
module.exports = () => { if (process.env.MY_ENVIRONMENT === 'production') { return { /* your production config */ }; } else { return { /* your development config */ }; } };
To use this configuration with Expo CLI commands, set the environment variable either for specific commands or in your shell profile. To set environment variables for specific commands, prefix the command with the variables and values as shown in the example:
Terminal
Copy
- MY_ENVIRONMENT=production eas update
This is not anything unique to Expo CLI. On Windows you can approximate the above command with:
Terminal
Copy
- npx cross-env MY_ENVIRONMENT=production eas update
Or you can use any other mechanism that you are comfortable with for environment variables.
You can use autocomplete and doc-blocks with an Expo config in TypeScript. Create an app.config.ts with the following contents:
app.config.ts
Copy
import { ExpoConfig, ConfigContext } from 'expo/config'; export default ({ config }: ConfigContext): ExpoConfig => ({ ...config, slug: 'my-app', name: 'My App', });
To import other TypeScript files into app.config.ts or customize the language features, we recommend using tsx
. tsx also enables using import syntax in any file imported by app.config.ts. This means you can write local config plugins
in TypeScript with full language features.
There are two different types of configs: static (app.config.json, app.json), and dynamic (app.config.js, app.config.ts). Static configs can be automatically updated with CLI tools, whereas dynamic configs must be manually updated by the developer.
({ config }) => ({}). This function can then mutate the static config values. Think of this like middleware for the static config.expo: {} object, then this will be used in place of the root object and all other keys will be ignored.Running npx expo config will display the final configuration that will be used in Expo CLI after resolution has occurred.