Управление config на React Native

Введение

В процессе разработки мобильных приложений на React Native, вы сталкиваетесь с задачей хранения и управления конфигурационными настройками. Настройки эти могут включать базовые URL для API, ключи доступа, флаги фич, параметры аналитики и другие данные, зависящие от окружения: разработки, тестирования или production. Корректная организация конфигов не только упрощает развертывание для разных сред, но и помогает избегать ошибок, связанных с тем, что "development"-данные случайно попадают в production. В этой статье я расскажу, как удобно и надёжно управлять конфигами в React Native, поделюсь готовыми примерами и дам практические рекомендации.

Что такое конфиг в контексте React Native

Прежде всего давайте уточним: под конфигом в React Native подразумевается набор переменных, управляющих поведением приложения без необходимости менять исходный код. Обычно выделяют следующие типы конфигов:

• Переменные окружения — ключи API, ссылки на серверы, способы логирования и пр.
• Флаги фич — включение/отключение определённых функций для конкретных сборок.
• UI-настройки — цвета, шрифты, значения по умолчанию.

Управление конфигурацией в React Native проектах может быстро стать сложным, особенно при работе с разными окружениями (development, staging, production) и секретными ключами. Чтобы не допускать ошибок и сделать этот процесс более управляемым, важно понимать, как правильно структурировать конфигурационные файлы, использовать переменные окружения и применять инструменты для их безопасного хранения и передачи. Если вы хотите детальнее погрузиться в управление конфигурацией и другими аспектами React Native разработки, — приходите на наш большой курс React Native и Expo Router. На курсе 184 уроков и 11 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Где и как хранить конфиг-файлы в React Native

Управление конфигом в React Native не такое простое, как в Node.js или чистом JS, потому что код разворачивается на мобильных платформах, и не все способы, знакомые по вебу, здесь подходят. Рассмотрим самые удобные методы:

.env файлы и react-native-dotenv

Один из самых популярных способов — использовать .env файлы в паре с библиотеками, которые читают их и делают переменные доступными в рантайме приложения.

Установка

Чтобы работать с переменными окружения, установите пакет react-native-dotenv или более универсальную библиотеку react-native-config.

npm install react-native-config
# или
yarn add react-native-config

Создание .env файлов

Создайте в корне проекта файлы для разных окружений:

• .env (общий)
• .env.development
• .env.staging
• .env.production

Пример содержимого файла:

API_URL=https://dev.api.myapp.com
GOOGLE_MAPS_KEY=somekeyfordev
FEATURE_X_ENABLED=true

Конфигурирование и использование

В файле кода вы импортируете значения следующим образом:

// Здесь мы импортируем переменную окружения из библиотеки
import Config from 'react-native-config'

// Теперь давайте используем значение API_URL в вашем коде:
console.log(Config.API_URL) // https://dev.api.myapp.com

Важно: После изменения .env файлов рекомендуется пересобрать проект, так как переменные подставляются на этапе сборки.

Работа с множеством окружений

Чтобы явно указать, какой .env файл использовать, при сборке приложения используйте скрипт, который подбирает нужный конфиг:

# Для ios
ENVFILE=.env.staging npx react-native run-ios

# Для android
ENVFILE=.env.production npx react-native run-android

Автоматизация через scripts

Добавьте в package.json удобные скрипты:

"scripts": {
  "android:staging": "ENVFILE=.env.staging npx react-native run-android",
  "android:prod": "ENVFILE=.env.production npx react-native run-android"
}

Теперь запуск сборки — дело одной команды.

Использование config.js

Иногда удобно держать конфиг прямо в JS-файле, особенно если переменные нужны только на уровне JS, и нет секрета, который попадёт в репозиторий.

Создайте файл:

// config.js

export default {
  API_URL: 'https://api.example.com',
  FEATURE_FLAG: true,
}

Использование:

import config from './config'

console.log(config.API_URL)

Этот способ прост, не требует дополнительных пакетов, но не даёт вам гибкости автосмены окружений и секреты, прописанные так, легко могут попасть в публичный доступ.

Как работает react-native-config под капотом

Когда вы используете react-native-config, библиотека на этапе сборки подменяет переменные прямо внутри native-кода (iOS и Android). Она генерирует natvie-файлы с этими константами, чтобы они были доступны через модуль в JS-коде.

Смотрите, как это выглядит для Android:

• Заполняется файл android/app/build.gradle
• Генерируется класс BuildConfig.java с нужными параметрами

Для iOS:

• Создаётся plist-файл с настройками

Это всё позволяет переменным быть недоступными через обычные JS-интерфейсы, чуть лучше защищая их от посторонних глаз.

Передача конфигов через build scripts

Вы можете сделать интеграцию более гибкой, добавив параметры, используемые только при сборке. Например, для поддержки CI/CD, где среда выбирается динамически:

ENVFILE=.env.$ENVIRONMENT npx react-native run-android

Здесь переменная ENVIRONMENT подставляется автоматически на стадии деплоя.

Пример использования переменных в коде

Я подготовил вам пример — смотрите, как сделать переключение бейс-урла в зависимости от сборки:

import Config from 'react-native-config'

const API_URL = Config.API_URL

async function fetchUserData(userId) {
  // Здесь мы используем переменную API_URL для запроса данных
  const response = await fetch(`${API_URL}/users/${userId}`)
  const data = await response.json()
  return data
}

Флаги фич (feature flags)

Отдельная категория — флаги функций. Они позволяют включать или отключать отдельные возможности приложения для разных окружений (например, экспериментальные фичи на dev).

Пример в .env:

SHOW_NEW_ONBOARDING=true

В коде:

if (Config.SHOW_NEW_ONBOARDING === 'true') {
  // Здесь можно отрендерить новый онбординг
}

Не забывайте: все переменные из .env приходят как строки! Сравнивать логические значения корректно через 'true'.

Использование секретов: Best Practices

Секреты (секретные ключи, токены) никогда не должны попадать в публичный репозиторий. Храните такие значения только в защищённых .env, добавляйте их в .gitignore:

.env*
!env.example

Создайте и поддерживайте публичный пример .env.example с шаблонными переменными, чтобы команде было удобно подключаться к проекту.

Доступность переменных на рантайме и hot reload

Обратите внимание, что переменные окружения не изменяются при hot reload. Чтобы изменения вступили в силу, нужно полностью пересобрать приложение.

Если вам нужно динамически менять параметры во время работы приложения (например, переключать API между staging/production прямо в UI, без пересборки), храните такие значения во внутреннем state, AsyncStorage или других средствах.

Конфиг для E2E и автоматизации

В автоматических тестах (например, через Detox) часто удобно подменять конфиг или работать с отдельным .env.e2e файлом. Это делается подходом, аналогичным production/development:

ENVFILE=.env.e2e npx detox test

Пример рабочей структуры конфигов в проекте

Вот структура каталога, который помогает избежать путаницы:

myApp/
  .env
  .env.production
  .env.staging
  .env.development
  .env.example
  src/
    config/
      index.js
  app.json
  package.json

• Все .env файлы — в корне, не в репозитории (кроме .example)
• JS-конфиги — в src/config
• Документация по переменным — рядом с .env.example

Особенности работы на Android и iOS

Нужно учитывать некоторые platform-specific нюансы:

Android

• Конфиг внедряется через BuildConfig.java, доступен в Java и в JS.
• Вы можете обращаться к переменным даже из native Java-кода.

iOS

• Переменные внедряются в Info.plist (или через Swift/Objective-C).
• После установки новых .env всегда перезапускайте Xcode/пересобирайте проект.

Конфигурирование в Expo

Expo поддерживает переменные окружения с помощью expo-constants, но только для переменных, объявленных в app.json. Для большего удобства с custom builds используйте библиотеки, описанные выше, либо переходите на bare workflow.

Пример для Expo:

import Constants from 'expo-constants'

console.log(Constants.manifest.extra.myCustomEnv)

В app.json:

"extra": {
  "myCustomEnv": "devvalue"
}

Если работаете с EAS Build (cloud-сборки Expo), то используйте Secrets для конфигов: они доступны только на этапе сборки.

Работа с чувствительными данными

Если нужна максимальная защита секретных переменных, храните их в Secure Storage и получайте с сервера после входа пользователя — так их не извлечь из static-ресурсов apk/ipa. Однако такой подход требует наличия дополнительной инфраструктуры.

Хранение runtime-конфига

Бывает, что параметры должны подгружаться с сервера "на лету". Можно реализовать хранилище, которое обновляется через fetch/post-запросы и сохраняет локально (например, через AsyncStorage).

Пример:

import AsyncStorage from '@react-native-async-storage/async-storage'

async function fetchConfig() {
  const response = await fetch('https://api.example.com/config')
  const config = await response.json()
  await AsyncStorage.setItem('runtimeConfig', JSON.stringify(config))
}

async function getConfig() {
  const config = await AsyncStorage.getItem('runtimeConfig')
  return config ? JSON.parse(config) : null
}

Этот способ полезен для фич, которые вы включаете или отключаете без релиза.

Управление конфигами в команде

Для командной работы используйте git hooks или CI/CD для автоматической подстановки конфигов. Рассмотрите инструменты типа dotenv-vault, чтобы безопасно делиться секретами между коллегами/системами.

Заключение

Грамотно настроенный и хорошо структурированный конфиг в React Native-проекте — базовая часть производственного процесса. Экспортируйте переменные только в нужных контекстах, инкапсулируйте sensitive-данные, автоматизируйте переключение окружений через скрипты и CI, поддерживайте чистоту репозитория, не коммитя секреты. Используйте готовые решения (например, react-native-config), чтобы не изобретать велосипед, и следите за тем, чтобы настройки не приводили к утечкам данных.

Эффективное управление конфигурацией — важный аспект разработки React Native приложений, но это лишь часть картины. Чтобы создавать надежные и масштабируемые приложения, необходимо глубокое понимание компонентов, навигации, управления состоянием и других ключевых концепций. Начните с основ и двигайтесь к более сложным темам, изучая нативные модули, анимацию и публикацию приложений. На нашем курсе React Native и Expo Router вы найдете все необходимые знания и навыки. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в мир React Native прямо сегодня.

Частозадаваемые технические вопросы по теме

Как поменять конфиг уже собранного приложения без новой сборки?

Это невозможно при использовании .env-файлов и react-native-config — переменные встраиваются на этапе сборки. Для гибкости подгружайте переменные из API при старте приложения или храните их в удалённом storage.

Могу ли я использовать разные конфиги для разных flavor (variant) Android?

Да, react-native-config поддерживает flavors. Создавайте файлы .env.dev, .env.prod, .env.staging, прописывайте различные productFlavors в build.gradle, и библиотека подхватит нужный конфиг автоматически.

Не проходят автоматические тесты, переменные не видны в тестовой среде

Проверьте, что вы используете правильный .env для тестовой среды (например, .env.test или .env.e2e) и запускаете скрипт с указанием ENVFILE. После смены .env пересоберите приложение.

Как исключить .env из публичного доступа, но не потерять его в CI?

Добавьте .env в .gitignore и храните секреты в безопасном месте. В CI/CD пайплайне импортируйте .env через секретные переменные среды — инструменты вроде GitHub Actions и GitLab CI поддерживают безопасную передачу переменных.

Почему react-native-config не работает с Expo Go?

Expo Go работает только на JS, а не на нативных модулях, поэтому react-native-config не поддерживается полностью. Используйте extra поля в app.json и expo-constants для простых кейсов или переходите на bare workflow Expo для более сложных сценариев.