React Native Environment Variables and Secrets: A Safe Configuration Workflow

Overview

A React Native app usually needs configuration such as an API base URL, an application identifier, feature flags, analytics settings, and push notification metadata. These values often differ by environment. Development may use a local or test server, staging may point to a shared QA system, and production should use the live service.

The important distinction is whether a value is public client configuration or a secret. Anything bundled into a mobile application can eventually be inspected. A value that must remain confidential, such as a database password, private signing credential, payment secret, or server-to-server token, must stay on a backend or in a protected build system. Environment variables can prevent accidental hard-coding, but they do not make a value secret once it is included in the app bundle.

Use this decision table before adding a variable:

Checklist by scenario

1. Define a predictable naming scheme

Choose environment names before creating files or CI variables. A practical baseline is development, staging, and production. Use one vocabulary across package scripts, Expo build profiles, native configuration, monitoring dashboards, and deployment documentation.

Prefer explicit names such as API_BASE_URL, APP_ENV, and ENABLE_EXPERIMENTAL_FEATURE. Avoid ambiguous names such as URL or KEY. Document whether each value is required, public, optional, or restricted to a particular platform.

2. Configure local development

Keep local environment files out of version control when they contain machine-specific values or credentials. Commit a safe template such as .env.example with placeholder values and a short explanation for each variable:

APP_ENV=development
API_BASE_URL=http://localhost:3000
EXPO_PUBLIC_ANALYTICS_ENABLED=false

For Expo projects, variables intended for use in application code are commonly exposed with the EXPO_PUBLIC_ prefix. Treat every such value as public: it is suitable for non-secret configuration, not passwords or private API credentials. The exact loading and substitution behavior depends on the Expo and build setup, so confirm it against the project’s current configuration rather than assuming that every variable is available everywhere.

For projects with native Android and iOS folders, decide whether values are supplied during the native build, through app configuration, or through a library that maps environment values into native resources. Keep that decision documented. Mixing several mechanisms without a clear boundary makes it difficult to know which value a release actually used.

3. Create staging and production profiles

Use separate build profiles or CI jobs for staging and production. Each profile should select the intended environment, application identifier, backend endpoint, and release behavior. A staging build should be visually distinguishable from production where practical, for example through an app label, banner, or build metadata.

Do not rely only on a developer’s local shell when producing a release. The build command should make the target environment explicit, and the resulting artifact should contain enough non-sensitive metadata to identify it during testing. For Expo-based workflows, keep environment selection aligned with the project’s build profiles and app configuration. For bare React Native workflows, apply the same principle to Gradle, Xcode schemes, and native configuration files.

4. Add variables to CI safely

Store protected values in the CI provider’s encrypted secret or variable store, and scope them to the smallest practical environment. Public values may be ordinary build variables, but review logs carefully: a public value can still reveal internal infrastructure or create confusion if it is wrong.

A generic GitHub Actions pattern looks like this:

env:
  APP_ENV: staging
  API_BASE_URL: ${{ vars.STAGING_API_BASE_URL }}
  PRIVATE_BUILD_TOKEN: ${{ secrets.PRIVATE_BUILD_TOKEN }}

The names and syntax differ across CI systems. The durable practice is to separate public configuration from secrets, avoid printing secret values, and make the selected environment visible in the job summary. Never commit a real .env file merely to make a CI build pass.

5. Validate configuration at startup

Fail early when a required value is missing or malformed. A small validation module can check the environment name, require an HTTPS production endpoint, and reject placeholder values:

const required = (name: string, value: string | undefined) => {
  if (!value) throw new Error(`Missing configuration: ${name}`);
  return value;
};

export const config = {
  appEnv: required('APP_ENV', process.env.APP_ENV),
  apiBaseUrl: required('API_BASE_URL', process.env.API_BASE_URL),
};

Adapt the access pattern to the configuration system your app uses. The key idea is to validate at a controlled boundary, rather than allowing an undefined URL or incorrect feature flag to fail later inside a network request or screen.

What to double-check

• Bundle exposure: inspect the built application and source maps according to your release process. Assume client-side values are discoverable.
• Environment selection: confirm the build command, profile, native scheme, and CI job all target the same environment.
• Endpoint safety: production must not point to a local, staging, or debug service. Staging must not silently write to production data.
• Platform parity: test Android and iOS separately when native configuration, push notifications, URL schemes, or application identifiers differ.
• Logging: search build logs and application logs for tokens, authorization headers, private keys, and complete environment dumps.
• Fallback behavior: decide whether a missing optional value disables a feature, while a missing required value stops the build or app startup.
• Rotation path: document how to replace a compromised value and how to publish a new build when a value is embedded at build time.

Environment configuration also intersects with release quality. Include configuration checks in automated tests where possible, and use a staging build for end-to-end verification. The React Native testing strategy can help you decide where configuration validation belongs. Before release, combine this work with a production readiness checklist.

Common mistakes

Calling an API key a secret

Many mobile SDKs require an identifier in the application. That identifier may be intended for client use, but it should still be restricted by the provider where possible. Do not assume that renaming it, encoding it, or placing it in an environment file protects it.

Using one file for every environment

A single mutable file encourages accidental production builds with test endpoints. Prefer explicit profiles and reviewable configuration. If files are used, make the active selection obvious and keep templates alongside the project documentation.

Reading variables in the wrong layer

JavaScript, Metro, Expo configuration, Gradle, and Xcode do not automatically share variables in the same way. A value available to a build script may not be available at runtime, and a JavaScript variable may not change a native resource already generated. Trace each variable from its source to its final consumer.

Silently falling back to production

Fallbacks can hide misconfiguration. A missing API URL should not quietly become the production URL during development or CI. Prefer an explicit error or a clearly labeled safe default.

Persisting sensitive tokens casually

Build-time configuration and user authentication data are different concerns. Do not place access tokens in source files or ordinary preferences without reviewing the platform storage requirements. Use an appropriate secure storage approach and define token expiration and logout behavior separately from environment management.

When to revisit

Review this workflow whenever you add an environment, change an Expo or React Native build tool, introduce a native module, move to a new CI provider, rotate a credential, or change API ownership. Revisit it before seasonal planning cycles and before a major release, even if the application code has not changed.

Use this short release check:

1. Identify the intended environment and record the build profile or CI job.
2. Compare the resolved API endpoint and app metadata with the release ticket.
3. Confirm that no secret is bundled, logged, or committed.
4. Run startup validation and a basic authenticated flow against the correct backend.
5. Test the release artifact on both target platforms when native settings differ.
6. Record how to rotate or revoke every credential involved in the release.

Keep .env.example, CI documentation, build profiles, and release checklists synchronized. That small maintenance habit makes React Native secrets management easier to audit and reduces the chance that a configuration change becomes a production incident.