Как использовать переменные среды в React

Если у вас нет опыта server side программирования, переменные среды могут показаться чем-то магическим. Этот недостаток знаний может поставить вас в тупик, когда вы закончите создавать приложения todo на localhost и попытаетесь создать продакшн сборку в первый раз. Если вы хотите узнать, как использовать переменные среды в ваших собственных инструментах, или глубоко погрузиться в то, как переменные среды работают в React, вы можете продолжить чтение этой статьи. Но если вы ищете быстрое решение и используете Create React App, ознакомьтесь с документацией здесь. Пользователи NextJS, ознакомьтесь с документацией здесь.

Проблема, которую мы решаем

Как объявить различные URL-адресов API для локальной разработки и для продакшн сборки.

Как решить эту проблему

Использовать переменные среды. При работе с React переменные среды — это переменные, доступные через глобальный объект process.env. Этот глобальный объект предоставляется вашей средой через NodeJS. И поскольку у нас нет NodeJS в браузере, нам понадобится webpack. В этой статье рассмотрим два способа установки и использования переменных среды для ваших React проектов с помощью webpack: с помощью скриптов npm и с помощью файла .env.

Способ 1: Использование скриптов npm для установки переменных среды

Во-первых, установите webpack и webpack-cli из npm:

npm install --save-dev webpack webpack-cli

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

{
  // ...
  scripts: {
    "dev": "webpack --config webpack.config.dev.js",
    "build": "webpack --config webpack.config.build.js"
  }
}

Давайте добавим некоторые переменные окружения с флагом --env в scripts:

{
  // ...
  scripts: {
    "dev": "webpack --env.API_URL=http://localhost:8000 --config webpack.config.dev.js",
    "build": "webpack --env.API_URL=https://www.myapi.com --config webpack.config.build.js"
  }
}

Мы добавили --env.API_URL= часть в обоих скриптах. Теперь запустите команду npm run dev, перейдите к React компоненту и используйте process.env.API_URL:

const App = () => <h1>{process.env.API_URL}</h1>;

И тут проект должен сломаться.

Сломается он потому, что когда мы используем переменные окружения в клиентском коде, они на самом деле просто служат заполнителями, которые будут заменены при компиляции нашего кода. Проблема в том, что мы не сказали webpack скомпилировать эти переменные в реальные значения. Давайте сделаем это в нашем конфигурационном файле webpack с плагином DefinePlugin:

const webpack = require('webpack'); // DefinePlugin это часть webpack, поэтому это require обязателен

// возвращаем функцию из config файла
// переменная `env` будет просто объектом { API_URL: 'http://localhost:8000' }
// в ней будут содержаться все переменные среды, которые мы указали в package.json

module.exports = (env) => {
  // этот объект это сама конфигурация webpack
  return {
    plugins: [
      // добавим плагин в список плагинов
      new webpack.DefinePlugin({ `process.env.API_URL`: JSON.stringify(${env.API_URL}) })
    ]
  };
};

DefinePlugin требует, чтобы вы буквально определили свои «переменные среды». Вы также можете применить .reduce к переменным среды, чтобы получить объект:

module.exports = (env) => {
  // создаем объект из переменных среды
  const envKeys = Object.keys(env).reduce((prev, next) => {
    prev[`process.env.${next}`] = JSON.stringify(env[next]);
    return prev;
  }, {});

  return {
    plugins: [
      new webpack.DefinePlugin(envKeys)
    ]
  };
};

Если вы запустите команду сейчас, все скомпилируется, и ваш process.env.API_URL будет скомпилирован в правильный URL-адрес на основе переменной среды.

Способ 2: Использование файла .env для установки переменных среды

Вся идея здесь состоит в том, чтобы создать файл (называемый просто .env), заполненный переменными среды. Чтобы защитить пароли и другие значения переменных среды, добавьте файл .env в .gitignore. Фронтенд код будет ссылаться на одну и ту же переменную среды (process.env.API_URL) в обеих средах (при локальной разработке и на продакшене), но поскольку вы определили разные значения в своих .env, скомпилированные значения будут отличаться.

Создадим файл .env

Этот файл должен находиться в корневом каталоге проекта и называться .env. Добавим переменную:

API_URL=http://localhost:8000

Обработка файла .env

Теперь нам нужен какой-то способ обработки файлов и их содержимого. Для этого мы собираемся использовать популярный npm пакет под названием dotenv. Dotenv широко используется (create-react-app использует его). Он будет получать переменные из нашего файла .env и добавлять их в глобальный process.env.

$ npm install --save-dev dotenv

Добавление переменных в проект React

Есть одна проблема. Dotenv работает только на стороне сервера. А мы хотим использовать переменные среды на стороне клиента, на фронтенде. В данном случае мы разрабатываем клиентскую часть. И dotenv нужна какая-то среда для фактического хранения переменных. Здесь поможет Webpack. Воспользуемся плагином DefinePlugin в нашей webpack конфигурации:

const webpack = require('webpack');
const dotenv = require('dotenv');

module.exports = () => {
  // dotenv вернет объект с полем parsed 
  const env = dotenv.config().parsed;
  
  // сделаем reduce, чтобы сделать объект
  const envKeys = Object.keys(env).reduce((prev, next) => {
    prev[`process.env.${next}`] = JSON.stringify(env[next]);
    return prev;
  }, {});

  return {
    plugins: [
      new webpack.DefinePlugin(envKeys)
    ]
  };
};

При необходимости проверьте параметры конфигурации dotenv в документации на github. Вызов .config() в dotenv вернет объект со всеми переменными среды, установленными в вашем файле .env через поле parsed. Теперь давайте проверим наш React код:

const App = () => <h1>{process.env.API_URL}</h1>;

И это работает! Он показывает значение переменной среды API_URL, определенной в .env. Осталась только одна проблема: нам все еще нужно определить различные API_URL для локальной разработки и продакшена.

Различные переменные среды для разных сред

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

• .env (содержит все переменные среды для продакшн)
• .env.development (содержит все переменные среды для локальной разработки)

Чтобы было ясно: мы добавляем к имени файла .env сопоставление имени среды. Общепринятой практикой является использование исходного файла .env для продакшн сборки, поэтому мы не будем добавлять постфикс для продакшн .env .

Настройка активной среды с помощью scripts в package.json

Мы собираемся использовать scripts (как мы это делали в методе 1), чтобы установить текущую среду в нашем package.json:

{
  "scripts": {
    "dev": "webpack --env.ENVIRONMENT=development --config webpack.config.dev.js",
    "build": "webpack --env.ENVIRONMENT=production --config webpack.config.build.js"
  }
}

Так как мы определили нашу среду в нашем package.json, теперь она доступна в нашей конфигурации webpack. Следующим шагом будет переход к webpack конфигурации и дать ему использовать файл .env, принадлежащий активной среде. Как и раньше, мы используем dotenv, но теперь мы указываем пользовательский path в параметрах.

const webpack = require('webpack');
const dotenv = require('dotenv');
const fs = require('fs'); // для проверки существования файла
const path = require('path'); // для получения текущего пути

module.exports = (env) => {
  // получаем корневой путь (предполагаем, что webpack config лежит в корне проекта)
  const currentPath = path.join(__dirname);
  
  // путь по умолчанию (будет использован для продакшена - `.env`)
  const basePath = currentPath + '/.env';

  // склеиваем имя среды с именем файла для получения имени env файла
  const envPath = basePath + '.' + env.ENVIRONMENT;

  // проверяем существует ли env файл, если нет используем имя по умолчанию
  const finalPath = fs.existsSync(envPath) ? envPath : basePath;

  // устанавливаем параметр path в dotenv
  const fileEnv = dotenv.config({ path: finalPath }).parsed;
  
  // сделаем reduce, чтобы получить объект
  const envKeys = Object.keys(fileEnv).reduce((prev, next) => {
    prev[`process.env.${next}`] = JSON.stringify(fileEnv[next]);
    return prev;
  }, {});

  return {
    plugins: [
      new webpack.DefinePlugin(envKeys)
    ]
  };

Эта вся необходимая настройка, но вы можете создать больше .env файлов для большего количества сред (например, .env.staging) по аналогии.

Содержание туториала по React JSX позволяет вам писать HTML-подобную разметку внутри файла JavaScript, сохраняя логику рендеринга и содержимое в одном месте. Иногда вам может понадобиться добавить немного логики JavaScript или сослаться на динамическое свойство внутри этой разметки. В этой ситуации вы можете использовать фигурные скобки в JSX, чтобы добавить в них JavaScript.

Передача строк в кавычках

Когда нужно передать строковый атрибут в JSX, нужно заключить его в одинарные или двойные кавычки:

export default function Avatar() {
  return (
    <img
      className="avatar"
      src="http://example.com/userpic.jpg"
      alt="User Name"
    />
  );
}

Здесь "http://example.com/userpic.jpg" и "User Name" передаются как строки. Но что, если вы хотите динамически указать src или alt? Вы можете использовать JavaScript значение, заменив " и " на { и }:

export default function Avatar() {
  const avatar = 'http://example.com/userpic.jpg';
  const description = 'User Name';
  return <img className="avatar" src={avatar} alt={description} />;
}

Обратите внимание на разницу между className="avatar", который указывает имя CSS класса "avatar", и src={avatar}, который считывает значение переменной JavaScript с именем avatar. Это потому, что фигурные скобки позволяют вам работать с JavaScript прямо в разметке.

Использование фигурных скобок: JavaScript в разметке

JSX — это особый способ написания JavaScript. Это означает, что внутри него можно использовать JavaScript — с помощью фигурных скобок { }. В приведенном ниже примере сначала объявляется имя, name, а затем оно встраивается в фигурные скобки внутри <h1>:

export default function TodoList() {
  const name = 'User Name';

  return <h1>{name}'s To Do List</h1>;
}

Любое выражение JavaScript будет работать между фигурными скобками, включая вызовы функций, таких как formatDate():

const today = new Date();

function formatDate(date) {
  return new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(date);
}

export default function TodoList() {
  return <h1>To Do List for {formatDate(today)}</h1>;
}

Где использовать фигурные скобки

Вы можете использовать фигурные скобки только двумя способами внутри JSX:

1. Как текст непосредственно внутри тега JSX: <h1>{name}'s To Do List</h1> работает, но <{tag}>To Do List</{tag}> работать не будет.
2. Поскольку атрибуты следуют сразу после знака =: src={avatar} будут считывать переменную avatar, но src="{avatar}" передаст строку "{avatar}".

Использование двойных фигурных скобок: CSS и другие объекты в JSX

Помимо строк, чисел и других выражений JavaScript, вы даже можете передавать объекты в JSX. Объекты также обозначаются фигурными скобками, например { name: "User Name", itemsCount: 10 }. Следовательно, чтобы передать объект JS в JSX, вы должны заключить объект в другую пару фигурных скобок: person={{ name: "User Name", itemsCount: 10 }}. Вы можете увидеть это со встроенными стилями CSS в JSX. React не требует от вас использования встроенных стилей (классы CSS отлично подходят для большинства случаев). Но когда вам нужен встроенный стиль, нужно передать объект атрибуту стиля:

export default function TodoList() {
  return (
    <ul
      style={{
        backgroundColor: 'black',
        color: 'pink',
      }}
    >
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </ul>
  );
}

Встроенные (inline) стили записываются в camelCase. Например, HTML <ul style="background-color: black"> в компоненте будет записан как <ul style={{ backgroundColor: 'black' }}>.

Другие примеры JavaScript объектов в фигурных скобках

Вы можете переместить несколько выражений в один объект и ссылаться на них в JSX внутри фигурных скобок:

const person = {
  name: 'User Name',
  theme: {
    backgroundColor: 'black',
    color: 'pink',
  },
};

export default function TodoList() {
  return (
    <div style={person.theme}>
      <h1>{person.name}'s Todos</h1>
      <img
        className="avatar"
        src="https://example.com/userpic.jpg"
        alt="userpic"
      />
      <ul>
        <li>Item 1</li>
        <li>Item 2</li>
        <li>Item 3</li>
      </ul>
    </div>
  );
}

В этом примере объект JavaScript person содержит строку имени и объект темы:

const person = {
  name: 'User Name',
  theme: {
    backgroundColor: 'black',
    color: 'pink',
  },
};

Компонент может использовать эти значения из person следующим образом:

<div style={person.theme}>
  <h1>{person.name}'s Todos</h1>

JSX очень минималистичен как язык шаблонов, потому что он позволяет вам организовывать данные и логику с помощью JavaScript.

Резюме

Теперь вы знаете почти все о JSX:

• Атрибуты JSX внутри кавычек передаются как строки.
• Фигурные скобки позволяют добавить в разметку логику и JavaScript переменные.
• Они работают внутри содержимого тега JSX или сразу после = в атрибутах.
• {{ и }} не являются специальным синтаксисом: это объект JavaScript, спрятанный внутри фигурных скобок JSX.