Environment variables

Stencil предоставляет мощный и гибкий механизм работы с переменными окружения, который позволяет настраивать сборку и поведение компонентов в зависимости от среды — разработки, тестирования или продакшена. Переменные окружения используются для конфигурации проекта, управления флагами функциональности и передачи чувствительных данных без их жесткого кодирования в исходный код.

Основы работы с переменными окружения

В Stencil переменные окружения определяются через объект process.env, аналогично Node.js. На этапе сборки значения этих переменных могут быть внедрены в код, что позволяет создавать условные блоки и конфигурации.

Пример использования:

const apiUrl = process.env.API_URL || 'http://localhost:3000';

В этом примере API_URL — переменная окружения, значение которой подставляется в код. Если переменная не задана, используется значение по умолчанию.

Определение переменных через .env файлы

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

  • .env — базовые значения для всех сред;
  • .env.development — значения для разработки;
  • .env.production — значения для продакшена.

Для их использования необходимо установить пакет dotenv и подключить его в конфигурации Stencil:

import { Config } from '@stencil/core';
import * as dotenv from 'dotenv';

dotenv.config();

export const config: Config = {
  namespace: 'my-app',
  globalScript: 'src/global/app.ts',
  devServer: {
    port: Number(process.env.PORT) || 3333
  }
};

При этом все переменные из .env становятся доступными через process.env.

Типизация переменных окружения

Для TypeScript-проектов важно обеспечить корректную типизацию переменных окружения. Создается файл env.d.ts с определением интерфейса:

interface ImportMetaEnv {
  readonly API_URL: string;
  readonly NODE_ENV: 'development' | 'production';
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

После этого переменные можно использовать безопасно, с поддержкой автодополнения и проверки типов:

const apiUrl: string = import.meta.env.API_URL;

Использование переменных в компонентах

Stencil позволяет внедрять значения переменных окружения непосредственно в компоненты через глобальные скрипты или напрямую:

import { Component, h, State } from '@stencil/core';

@Component({
  tag: 'app-config-demo',
  styleUrl: 'app-config-demo.css',
  shadow: true
})
export class AppConfigDemo {
  @State() apiUrl: string;

  componentWillLoad() {
    this.apiUrl = process.env.API_URL || 'http://localhost:3000';
  }

  render() {
    return (
      <div>
        <p>API URL: {this.apiUrl}</p>
      </div>
    );
  }
}

Использование @State обеспечивает реактивное обновление интерфейса при изменении значения.

Переменные окружения и условная сборка

Stencil поддерживает оптимизацию кода на основе переменных окружения. Например, можно включать или отключать функциональность для разных сред:

if (process.env.NODE_ENV === 'production') {
  console.log('Production mode: отключаем debug-логи');
} else {
  console.log('Development mode: включены debug-логи');
}

На этапе сборки такие блоки могут быть автоматически удалены с помощью tree-shaking и terser, что снижает размер финального бандла.

Динамическая подстановка и конфигурация

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

const config = {
  apiUrl: process.env.API_URL || 'http://localhost:3000',
  analyticsKey: process.env.ANALYTICS_KEY || ''
};

export default config;

Доступ к конфигурации можно получать в любом компоненте или сервисе, что упрощает управление настройками приложения.

Рекомендации по безопасности

  • Никогда не хранить чувствительные ключи напрямую в репозитории — использовать .env файлы и секреты CI/CD.
  • Ограничить доступ к переменным окружения на уровне сборки.
  • Для публичных фронтенд-проектов учитывать, что все значения, внедренные в код, будут доступны в браузере, и хранить только безопасные данные.

Интеграция с CI/CD

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

API_URL=https://api.example.com NODE_ENV=production npm run build

Это позволяет создавать разные сборки без изменения исходного кода и поддерживать единый процесс деплоя для всех сред.

Переменные окружения в Stencil обеспечивают гибкость конфигурации, безопасное управление данными и возможность условной сборки, что делает их важным инструментом при разработке масштабных и многослойных приложений.

Оглавление