Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 71 ยท Getting Started

Project Structure and App Config

Understand the files in an Expo project: app.json and app.config.ts, package.json, the Expo Router app folder, assets, EXPO_PUBLIC environment variables and tsconfig.

A React Native project is more than components. It has files that describe your app to the operating system (its name, icon and identifiers), files that list dependencies and scripts, and folders that follow conventions your tools rely on. Knowing what each file does saves hours when something goes wrong. This lesson tours the important ones and explains how configuration and environment variables work in an Expo project.

Real and stand-in. The files below are real project files, shown read-only. The two runnable examples are stand-ins: plain JavaScript that behaves like the config resolution and the environment-variable rule, so you can experiment without a build tool.

The top level

TEXT
my-app/
  app/                 routes (Expo Router)
  assets/              images, fonts
  components/          your reusable components
  constants/           colors and other shared values
  hooks/               custom hooks
  app.json             static app configuration
  package.json         dependencies, scripts
  tsconfig.json        TypeScript settings
  .env                 environment variables (not committed if secret)
  .gitignore

Folder names such as components/ and hooks/ are conventions of the template, not rules. The folder that matters to the tooling is app/ when you use Expo Router: every file inside is a screen (you will learn this in File-Based Routing with Expo Router). Two generated folders you will not edit are node_modules/ and, after a native build, ios/ and android/. Expo can regenerate those native folders from your config, so many teams do not commit them.

package.json

package.json lists dependencies and defines scripts, like in any Node project:

JSON
{
  "name": "my-app",
  "main": "expo-router/entry",
  "version": "1.0.0",
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "lint": "expo lint"
  },
  "dependencies": {
    "expo": "~54.0.0",
    "expo-router": "~6.0.0",
    "react": "19.1.0",
    "react-native": "0.81.0"
  }
}

The version numbers above are examples; your project will show the ones from your template. Two things to notice. The main field points at expo-router/entry, which is how the router becomes the app's entry point. And the expo version decides which compatible versions of React Native and every Expo package you should use. Install Expo packages with npx expo install <package> instead of npm install, because it picks the version that matches your SDK.

app.json: describing the app

app.json is read by Expo's tools, not by your running JavaScript. It sets the name on the home screen, the icon, the splash screen and platform identifiers:

JSON
{
  "expo": {
    "name": "My App",
    "slug": "my-app",
    "version": "1.0.0",
    "orientation": "portrait",
    "icon": "./assets/images/icon.png",
    "scheme": "myapp",
    "userInterfaceStyle": "automatic",
    "ios": {
      "bundleIdentifier": "com.example.myapp"
    },
    "android": {
      "package": "com.example.myapp"
    },
    "plugins": ["expo-router"]
  }
}
Field Meaning
name The app name users see
slug A URL-friendly id used by Expo services
version The user-visible version, such as 1.0.0
scheme The URL prefix for deep links, such as myapp://
userInterfaceStyle light, dark or automatic
ios.bundleIdentifier / android.package The unique app id on each store; it cannot change after you publish
plugins Config plugins that edit native projects at build time

The identifier is reverse-domain style (com.yourcompany.yourapp). Choose it carefully, because the stores treat a different identifier as a different app.

Where settings live

package.json Dependencies and scripts.
app.json Name, icon, ids, plugins.
.env Per-environment values.
app/ One file per screen.
1 / 2

app.config.ts: configuration as code

When a static file is not enough, replace app.json with app.config.ts (or .js). It exports a function that receives the existing config and returns the final one, so you can compute values, for example one app name per environment:

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

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: process.env.APP_VARIANT === 'dev' ? 'My App (Dev)' : 'My App',
  slug: 'my-app',
  ios: { bundleIdentifier: 'com.example.myapp' },
  android: { package: 'com.example.myapp' },
  extra: { apiBase: process.env.API_BASE },
});

This file runs in Node on your computer at build time, so process.env reads your shell environment there. The values you put under extra become available to your app code through Constants.expoConfig?.extra. Do not put secrets there: anything inside the app bundle can be extracted by someone with the app file.

Resolving config like app.config.ts

The same function, called with two environments, produces two different apps. That is how teams install a "dev" build next to the production one on the same phone: they have different identifiers.

Assets

Images, fonts and other files live in assets/. You import them with require, and the bundler includes them in the app:

TSX
import { Image } from 'react-native';

<Image source={require('../assets/images/logo.png')} style={{ width: 80, height: 80 }} />

Because require is resolved at build time, the path must be a literal string, not a variable. Files named icon.png, splash-icon.png and adaptive-icon.png are referenced from app.json. You will use images in depth in Images, Icons and Media.

Environment variables

Expo reads .env files. A variable whose name starts with EXPO_PUBLIC_ is inlined into your JavaScript bundle at build time and can be read as process.env.EXPO_PUBLIC_NAME:

TEXT
# .env
EXPO_PUBLIC_API_URL=https://api.example.com
SECRET_KEY=do-not-ship-this
TypeScript
const apiUrl = process.env.EXPO_PUBLIC_API_URL;  // available in the app
const secret = process.env.SECRET_KEY;            // undefined in the app

Variables without the prefix are available only to build-time tools such as app.config.ts. The prefix is a safety valve, but remember what "public" means: the value is visible to anyone who unpacks the app. A mobile app cannot keep a secret. API keys that grant real power belong on a server that your app calls. Read more in Mobile App Security.

Which variables reach the bundle?

TypeScript setup

New Expo projects use TypeScript by default. The generated tsconfig.json extends Expo's base settings and turns on strict mode:

JSON
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "paths": { "@/*": ["./*"] }
  },
  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
}

The paths entry lets you import with @/components/Card instead of long relative paths. TypeScript only checks types; Metro uses Babel to strip them, so a type error will not stop the app from running. Run npx tsc --noEmit in CI to catch them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file sets the app's display name, icon and bundle identifier?

    app.json or app.config.ts describes the app to Expo's build tools: name, icon, identifiers and plugins.
  2. 2. A variable named API_SECRET in .env (no prefix) is read in your component with process.env.API_SECRET. What do you get?

    Only variables with the EXPO_PUBLIC_ prefix are inlined into the app. And even those are public: anyone can read them from the app file.
  3. 3. Why use app.config.ts instead of app.json?

    app.config.ts exports a function, so values can depend on environment variables or logic. app.json is static.
  4. 4. Which command should you use to add an Expo package so the version matches your SDK?

    npx expo install picks a version compatible with your installed Expo SDK.

Summary

  • package.json holds dependencies and scripts; its main field points at expo-router/entry when you use Expo Router.
  • app.json (or app.config.ts) describes the app: name, icon, scheme, identifiers and plugins. Changes often need a new native build.
  • Identifiers like com.example.myapp are permanent once you publish.
  • Only EXPO_PUBLIC_ variables reach your code, and they are visible to anyone; keep real secrets on a server.
  • TypeScript is the default; types are checked by tsc, not by Metro.

Now meet the components themselves in Core Components: View, Text, Image.