Zum Hauptinhalt springen

Globale Konfiguration

Einführung​

Bei der globalen Konfiguration handelt es sich um anwendungsweite Daten, die zentral im globalen Speicher gespeichert sind und auf die während der gesamten Lebensdauer Ihrer Anwendung zugegriffen werden kann. Nachdem Ihre Anwendung initialisiert wurde (siehe Anwendungseinrichtung), wird die Konfiguration global gespeichert. Sie können dann Werte überall in Komponenten, Diensten, Hilfsprogrammen oder API-Clients abrufen, aktualisieren und verwalten.

Auf dieser Seite werden die APIs zur Verwendung der globalen Konfiguration behandelt:

  • Konfigurationsdateien: Strukturieren und Speichern von Konfigurationen in Ihrem Projekt.
  • Umgebungsvariablen: Bereitstellen einer alternativen Quelle für Konfigurationswerte, die Vorrang vor Konfigurationsdateien hat.
  • getConfigValue(): Abrufen von Konfigurationswerten mit Fallback-Auflösung, wobei zuerst die Umgebungsvariablen und dann der globale Speicher überprüft werden.
  • loadConfiguration(): Laden und Initialisieren der Konfiguration (wird normalerweise während der App-Initialisierung aufgerufen).
  • setConfiguration(): Programmgesteuerte Aktualisierung der globalen Konfiguration zur Laufzeit.
  • getConfiguration(): Direkter Zugriff auf das gesamte Konfigurationsobjekt.

Verwenden Sie diese Anleitung, um die globale Konfiguration in Ihren Jutro-Anwendungen zu implementieren.

Anwendungsinitialisierung ermöglicht globale Konfiguration​

Während der Initialisierungsphase wird die Konfiguration Ihrer Anwendung über die Funktion loadConfiguration() in einen globalen Speicher geladen. Dies erfolgt einmalig beim Start:

// startApp.js (runs once at app startup)
import { loadConfiguration } from '@jutro/config';
import appConfig from './config/config.json';

loadConfiguration(appConfig); // ← Populates global store

start(Jutro, {
  /* ... */
});

Nach Abschluss der Initialisierung können Sie überall in der Anwendung auf diese gespeicherten Werte zugreifen und sie verwalten.

Konfigurationsquellen​

Konfigurationswerte stammen aus mehreren Quellen:

  • Globaler Speicher: JavaScript-Objekt im Arbeitsspeicher, das Ihre Konfiguration enthält. Wird durch Aufrufen von loadConfiguration() mit Daten aus den JSON-Konfigurationsdateien wie src/config/config.json gefüllt.
  • Umgebungsvariablen: In der .env-Datei definierte Werte (mit dem Präfix REACT_APP_ oder JUTRO_), die zur Laufzeit in process.env geladen werden. Die Funktion getConfigValue() prüft process.env beim Abrufen von Werten.
  • Bereitstellungsvariablen: In Jutro Web Apps definierte Werte, die zur Laufzeit eingefügt werden und mit loadConfiguration() in den globalen Speicher geladen werden können. Weitere Informationen finden Sie in der Dokumentation zu Jutro Web Apps.

Umgebungsvariablen werden nicht in den globalen Speicher übernommen. Stattdessen wird beim Aufrufen von getConfigValue() zunächst process.env überprüft, bevor der globale Speicher durchsucht wird. Dadurch werden Umgebungsvariablen von Ihrer Anwendungskonfiguration getrennt gehalten, können aber dennoch Vorrang haben. Dieses Verhalten lässt sich mit JUTRO_NEW_CONFIG_LOADING_ORDER=true umkehren, sodass zuerst der globale Speicher überprüft wird. Details finden Sie unter Ladereihenfolge von Umgebungsvariablen.

Globale Konfiguration für eine Anwendung verwenden​

Es wird empfohlen, die Konfiguration in der Datei src/config/config.json zu zentralisieren. Diese einzelne Datei dient als Standardspeicherort für alle globalen Konfigurationswerte und wird bei der Initialisierung der Anwendung automatisch geladen, nachdem diese eingerichtet ist.

Wenn es spezifische Gründe dafür gibt, die Konfiguration auf mehrere Dateien aufzuteilen, können Sie zusätzliche JSON-Dateien im Verzeichnis src/config/ erstellen und bei Bedarf laden.

Konfigurationsdatei erstellen​

  1. Erstellen Sie eine JSON-Datei im Verzeichnis src/config/, z. B. src/config/config.json.

  2. Fügen Sie Ihre Konfigurationswerte in der Datei ein:

    {
      "dashboardUrl": "https://example-dashboard.com",
      "apiTimeout": 5000,
      "featureFlags": {
        "enableNewFeature": true
      }
    }

  3. Importieren Sie die Konfigurationsdatei in die startApp-Datei, sodass sie während der Initialisierung geladen wird:

    import { loadConfiguration } from '@jutro/config';
    import appConfig from './config/config.json';

    loadConfiguration(appConfig);

  4. Verwenden Sie die Werte in Ihrer Anwendung mit einer der verfügbaren Optionen:

    • getConfigValue (API hier verfügbar)

      import { getConfigValue } from '@jutro/config';

      <Link
        href={getConfigValue('dashboardUrl')}
        icon="gw-code"
      />;

    • getConfiguration (API hier verfügbar)

      import { getConfiguration } from '@jutro/config';

      const config = getConfiguration();
      <Link
        href={config.dashboardUrl}
        icon="gw-code"
      />;

Konfigurationsschlüssel zur vorhandenen Konfigurationsdatei hinzufügen​

Voraussetzung: Die Initialisierung Ihrer Anwendung muss konfiguriert sein. Details finden Sie unter Anwendungseinrichtung.

  1. Fügen Sie Ihren Wert in src/config/config.json hinzu:

    {
      "dashboardUrl": "https://example-dashboard.com"
    }

  2. Verwenden Sie den Wert in der Anwendung:

    import { getConfigValue } from '@jutro/config';

    <Link
      href={getConfigValue('dashboardUrl')}
      icon="gw-code"
    />;

Konfigurationsdateien direkt importieren​

Note: Dieser Ansatz ist eine Alternative zur globalen Konfiguration und nicht Teil des globalen Konfigurationssystems. Direkt importierte Werte werden nicht im globalen Speicher gespeichert und sind nur dort verfügbar, wohin sie importiert wurden.

  1. Öffnen Sie eine vorhandene Konfigurationsdatei oder erstellen Sie eine JSON-Datei im Verzeichnis src/config/, z. B. src/config/urlConfig.json.

  2. Fügen Sie den Wert in der Konfigurationsdatei hinzu:

    {
      "dashboardUrl": "https://example-dashboard.com"
    }

  3. Verwenden Sie den Wert in der Anwendung:

    import urlConfig from './config/urlConfig.json';

    <Link
      href={urlConfig.dashboardUrl}
      icon="gw-code"
    />;

Umgebungsvariablen in der Konfiguration​

Umgebungsvariablen bieten eine alternative Möglichkeit, Konfigurationswerte festzulegen, ohne die Projektdateien zu ändern. Dies ist nützlich für bereitstellungsspezifische Einstellungen oder umgebungsspezifische Überschreibungen.

Wenn Sie einen Konfigurationsschlüssel in einer Umgebungsvariablen definieren, hat dieser automatisch Vorrang vor dem gleichen Schlüssel in Ihren Konfigurationsdateien, wenn Sie getConfigValue() aufrufen. Die Umgebungsvariable aktualisiert nicht die tatsächliche Umgebung, sondern wirkt sich nur auf die Ausgabe von getConfigValue() aus.

So erstellen Sie eine Umgebungsvariable:

  1. Erstellen Sie eine .env-Datei im Stamm der Jutro-Anwendung.

  2. Fügen Sie den Wert mit einem REACT_APP_-Präfix hinzu, beispielsweise:

    REACT_APP_JUTRO_LOGGER_LEVEL=DEBUG

  3. Lesen Sie den Wert in der Anwendung:

    const loggerLevel = process.env.JUTRO_LOGGER_LEVEL;

    oder:

    const loggerLevel = getConfigValue('loggerLevel');
Note: Wenn Sie SAFE_ENV=true in der .env-Datei hinzufügen, sind nur Variablen zulässig, die mit JUTRO_ oder REACT_APP_ beginnen. Dies entspricht den Regeln für Umgebungsvariablen in React-Anwendungen.

Konfigurationswerte mit Umgebungsvariablen überschreiben​

Sie können Umgebungsvariablen verwenden, um Konfigurationswerte zu überschreiben, ohne Ihre Konfigurationsdateien zu ändern. Dies ist nützlich für verschiedene Bereitstellungsumgebungen.

Wenn die Konfigurationsdatei z. B. Folgendes enthält:

{
  "dashboardUrl": "https://prod-dashboard.com",
  "apiTimeout": 5000
}

Und die .env-Datei Folgendes enthält:

REACT_APP_dashboardUrl=https://dev-dashboard.com

Wenn Sie dann getConfigValue() aufrufen, hat die Umgebungsvariable Vorrang:

getConfigValue('dashboardUrl'); // Returns: https://dev-dashboard.com (from .env)
getConfigValue('apiTimeout'); // Returns: 5000 (from config file)

Konfigurationsfunktionen​

getConfigValue​

Parameter​

patherforderlich​

Typ
string
Beschreibung

The object path to the configuration value. Supports dot notation for nested values.

defaultValue​

Typ
boolean | string | object | number
Beschreibung

The default value returned if no value is found at the given path.

Verwendung​

Die Funktion getConfigValue ruft Konfigurationswerte mit Fallback-Auflösung ab. Die Suchreihenfolge beim Aufruf von getConfigValue(key) lautet wie folgt:

  1. Überprüfen von process.env.REACT_APP_key auf Umgebungsvariablenwerte (Punkte werden in Unterstriche umgewandelt).
  2. Überprüfen von process.env auf eine exakte Schlüsselübereinstimmung.
  3. Überprüfen des globalen Speichers auf den Schlüssel mittels Durchlaufen verschachtelter Eigenschaften:
    • Wenn der Schlüssel Punkte enthält (z. B. 'database.host'), wird die verschachtelte Objektstruktur durchlaufen.
    • Wenn der Schlüssel flach ist (z. B. 'JUTRO_PC_CLOUD_API_URL'), wird er als exakte Eigenschaft abgerufen.
  4. Verwenden des angegebenen Standardwerts, wenn bei keinem der oben genannten Fälle der Schlüssel enthalten ist.

Bei der grundlegenden Verwendung mit einem einfachen Wert überprüft die Funktion zunächst die Umgebungsvariablen (mit dem Präfix REACT_APP_) und greift dann auf den globalen Speicher der Konfiguration zurück. Wenn keiner der beiden Werte vorhanden ist, wird der angegebene Standardwert verwendet.

import { getConfigValue } from '@jutro/config';

const apiUrl = getConfigValue('apiUrl', 'https://api.default.com');

Bei Verwendung in React-Komponenten rufen Sie Konfigurationswerte in Ihren Komponenten ab, um das Verhalten basierend auf umgebungsspezifischen Einstellungen zu steuern.

import { getConfigValue } from '@jutro/config';

export const ApiClient = () => {
  const endpoint = getConfigValue('api.endpoint');

  return (
    <div>
      <a href={endpoint}>API Documentation</a>
    </div>
  );
};

Standardmäßig haben Umgebungsvariablen Vorrang vor Konfigurationsdateiwerten. Durch Aktivieren von JUTRO_NEW_CONFIG_LOADING_ORDER=true lässt sich dieses Verhalten für zur Laufzeit geladene Konfigurationen umkehren.

// With config.json = { timeout: 5000 } and REACT_APP_TIMEOUT=30000
const timeout = getConfigValue('timeout');
// Result: 30000 (environment variable takes priority)

Geben Sie immer einen Standardwert für optionale Konfigurationsschlüssel an, um sicherzustellen, dass Ihre Anwendung ein angemessenes Fallback-Verhalten aufweist.

const port = getConfigValue('server.port', 3000);
const isDev = getConfigValue('environment.isDevelopment', false);
Zugriff auf Konfigurationswerte durch exakte Schlüsselübereinstimmung​

Sie können auf flache Schlüssel anhand ihres genauen Namens zugreifen. Dies gilt für Umgebungsvariablen ebenso wie für Werte im globalen Speicher der Konfiguration.

In der .env-Datei (ohne Präfix REACT_APP_):

MY_CUSTOM_VAR=customValue

Im globalen Speicher (z. B. Bereitstellungsvariablen):

// Merged into config using loadConfiguration({ ...appConfig, ...appConfig.env })
{
  "JUTRO_PC_CLOUD_API_URL": "https://...",
  "JUTRO_AUTH_CLIENT_ID": "abc123"
}

Zugriff auf beide:

// From .env (step 2: exact match in process.env)
const customVar = getConfigValue('MY_CUSTOM_VAR'); // Returns: customValue

// From global store (step 3: exact match in config object)
const apiUrl = getConfigValue('JUTRO_PC_CLOUD_API_URL'); // Returns: https://...
const authId = getConfigValue('JUTRO_AUTH_CLIENT_ID'); // Returns: abc123
Zugriff auf verschachtelte Konfigurationswerte​

Verwenden Sie die Punktnotation, um auf verschachtelte Konfigurationswerte in Ihrer Konfiguration zuzugreifen. Das Verhalten unterscheidet sich bei Umgebungsvariablen und Konfigurationswerten:

  • Umgebungsvariablen: Punkte werden in Unterstriche umgewandelt und mit dem Präfix REACT_APP_ versehen. getConfigValue('database.host') sucht z. B. nach REACT_APP_DATABASE_HOST.
  • Konfigurationswerte: Punkte werden direkt für den Durchlauf verschachtelter Objekte verwendet. getConfigValue('database.host') sucht z. B. den Wert unter dem verschachtelten Pfad database.host in Ihrer Konfiguration.

Beispiel mit Umgebungsvariablen (.env-Datei):

REACT_APP_DATABASE_HOST=localhost
REACT_APP_DATABASE_PORT=5432
REACT_APP_API_ENDPOINT=https://api.example.com

Beispiel mit config.json:

{
  "database": {
    "host": "db.example.com",
    "port": 5432
  },
  "api": {
    "endpoint": "https://api.example.com"
  }
}

Zugriff im Code:

// Both read from the same logical key using dot notation
const dbHost = getConfigValue('database.host'); // Looks for REACT_APP_DATABASE_HOST, then config.database.host
const apiUrl = getConfigValue('api.endpoint'); // Looks for REACT_APP_API_ENDPOINT, then config.api.endpoint

Umgebungsvariablen werden zuerst überprüft. Wenn REACT_APP_DATABASE_HOST vorhanden ist, hat sie Vorrang vor config.database.host. Verwenden Sie JUTRO_NEW_CONFIG_LOADING_ORDER=true, um diese Priorität umzukehren.

loadConfiguration​

Parameter​

config​

Typ
Record<string, any>
Beschreibung

Configuration object containing custom configuration settings to be merged with the base configuration.

params​

Typ
Record<string, any>
Beschreibung

Map of parameters to be used in mustache template substitutions within the configuration values.

baseConfigVerworfen​

Typ
Record<string, any>
Beschreibung

Base configuration object merged by function with the provided config. Defaults to defaultConfig if not specified.

Verwendung​

Die Funktion loadConfiguration lädt und speichert Konfigurationsobjekte global und unterstützt dabei die Ersetzung von Vorlagenparametern. Verwenden Sie diese Funktion, um die Anwendungskonfiguration beim Start zu initialisieren.

Initialisieren Sie die Konfiguration mit Ihrem benutzerdefinierten Konfigurationsobjekt und speichern Sie es zur Verwendung in der gesamten Anwendung.

import { loadConfiguration } from '@jutro/config';

const customConfig = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
};

loadConfiguration(customConfig);

Verwenden Sie das Argument params, um Vorlagenvariablen in den Konfigurationswerten zu ersetzen. Dies ist nützlich für eine dynamische Konfiguration, die auf umgebungsspezifischen Parametern basiert.

import { loadConfiguration } from '@jutro/config';

const config = {
  apiUrl: 'https://{{apiHost}}/api',
  logoUrl: 'https://{{cdnHost}}/logo.png',
};

const params = {
  apiHost: 'api.prod.example.com',
  cdnHost: 'cdn.example.com',
};

loadConfiguration(config, params);
// Results in: { apiUrl: 'https://api.prod.example.com/api', logoUrl: 'https://cdn.example.com/logo.png' }

Kombinieren Sie loadConfiguration mit getConfigValue, um Ihre Konfiguration zu initialisieren und dann bestimmte Werte in der gesamten Anwendung abzurufen.

import { loadConfiguration, getConfigValue } from '@jutro/config';

loadConfiguration({
  database: {
    host: 'db.example.com',
    port: 5432,
  },
});

const dbHost = getConfigValue('database.host');
Note: In der Dokumentation zu Jutro Web Apps finden Sie Informationen zur Verwendung von Bereitstellungsvariablen und zum Laden dieser Variablen in Ihre Konfiguration zur Laufzeit mithilfe von loadConfiguration.
Ladereihenfolge von Umgebungsvariablen​

Die Funktion loadConfiguration kann verwendet werden, um den Wert einer Umgebungsvariablen zur Laufzeit festzulegen, zum Beispiel:

import { loadConfiguration, getConfigValue } from '@jutro/config';

loadConfiguration({ REACT_APP_SAMPLE_ENV_VARIABLE: 'value' });
console.log(getConfigValue('REACT_APP_SAMPLE_ENV_VARIABLE'));
// "value" is printed to console

Die in Ihrer .env-Datei definierten Umgebungsvariablenwerte haben jedoch Vorrang vor den von der Funktion loadConfiguration festgelegten Werten. Dies ist der Fall, weil getConfigValue eine bestimmte Auflösungsreihenfolge implementiert. Umgebungsvariablen werden vor dem gespeicherten Konfigurationsobjekt überprüft. Das bedeutet, dass Sie den Wert neuer Variablen festlegen können, aber die Werte von in Ihrer .env-Datei festgelegten Build-Zeit-Variablen mit dieser Funktion nicht geändert werden können.

Um die Konfigurationspriorität zu ändern, können Sie JUTRO_NEW_CONFIG_LOADING_ORDER=true in Ihrer Umgebung angeben. Wenn diese Option aktiviert ist, hat der mit der Methode loadConfiguration zur Laufzeit geladene Wert Vorrang vor Ihrer .env-Datei.

setConfiguration​

Parameter​

configerforderlich​

Typ
Record<string, any>
Beschreibung

The configuration object to store in a globally accessible namespace so environment settings are available throughout the application. This object is shallow copied, meaning only root-level properties are duplicated. Nested objects and arrays remain as references to the originals, so modifications to nested structures affect the stored configuration.

Verwendung​

Die Funktion setConfiguration speichert ein Konfigurationsobjekt im globalen Namensraum. Diese Funktion wird normalerweise intern von loadConfiguration aufgerufen, aber Sie können sie direkt verwenden, wenn Sie die globale Konfiguration programmgesteuert aktualisieren möchten.

Die Funktion setConfiguration speichert ein Konfigurationsobjekt im globalen Namensraum, sodass es in allen Teilen der Anwendung global zugänglich ist.

import { setConfiguration, getConfigValue } from '@jutro/config';

const appConfig = {
  apiUrl: 'https://api.example.com',
  theme: 'dark',
  features: {
    analytics: true,
  },
};

setConfiguration(appConfig);

// Later, retrieve the stored config
const url = getConfigValue('apiUrl'); // 'https://api.example.com'

Verwenden Sie setConfiguration, um die globale Konfiguration zur Laufzeit zu aktualisieren. Dies ist nützlich, wenn die Konfiguration basierend auf Benutzeraktionen oder Laufzeitbedingungen dynamisch geändert werden muss.

import { setConfiguration, getConfigValue } from '@jutro/config';

// Initial config
setConfiguration({ userPreferences: { language: 'en' } });

// Update config based on user action
const updatedConfig = { userPreferences: { language: 'pl' } };
setConfiguration(updatedConfig);

const language = getConfigValue('userPreferences.language'); // 'pl'

Beachten Sie, dass beim flachen Kopieren verschachtelte Objekte als Referenzen erhalten bleiben. Wenn Sie verschachtelte Eigenschaften nach dem Aufrufen von setConfiguration ändern, werden diese Änderungen in der global gespeicherten Konfiguration übernommen.

import { setConfiguration, getConfigValue } from '@jutro/config';

const config = { database: { host: 'localhost' } };
setConfiguration(config);

// Modifying the original object's nested properties affects stored config
config.database.host = 'prod-db.example.com';

const dbHost = getConfigValue('database.host'); // 'prod-db.example.com'

getConfiguration​

Die Funktion getConfiguration hat keine Parameter und gibt das gesamte globale Konfigurationsobjekt zurück, das zuvor geladen wurde.

Verwendung​

Ruft das gesamte globale Konfigurationsobjekt ab, das über loadConfiguration oder setConfigurationfestgelegt wurde. Dadurch erhalten Sie direkten Zugriff auf die Rohkonfiguration, ohne auf die Auflösungslogik von getConfigValue angewiesen zu sein.

import { getConfiguration } from '@jutro/config';

const config = getConfiguration();
console.log(config);
// { apiUrl: 'https://api.example.com', timeout: 5000, ... }

Verwenden Sie getConfiguration, wenn Sie benutzerdefinierte Vorgänge für das gesamte Konfigurationsobjekt ausführen möchten, z. B. Filtern oder Transformieren von Werten zu Debugging-Zwecken.

import { getConfiguration } from '@jutro/config';

const config = getConfiguration();
const allKeys = Object.keys(config);
console.log('Available config keys:', allKeys);

Greifen Sie direkt auf verschachtelte Konfigurationseigenschaften zu, indem Sie die JavaScript-Objektsyntax anstelle des mit getConfigValue verwendeten Zeichenfolgenformats mit Punktnotation verwenden.

import { getConfiguration } from '@jutro/config';

const config = getConfiguration();
const dbHost = config.database.host;
const dbPort = config.database.port;

Kombinieren Sie getConfiguration mit setConfiguration, um spezifische Konfigurationswerte zu aktualisieren und andere Einstellungen beizubehalten.

import { getConfiguration, setConfiguration } from '@jutro/config';

const currentConfig = getConfiguration();
const updatedConfig = {
  ...currentConfig,
  theme: 'light',
};

setConfiguration(updatedConfig);

Zusätzliche Konfigurationsoptionen​

React Strict Mode​

Der React Strict Mode ist eine native React-Komponente, die zusätzliche Prüfungen ausführt, wenn sie in einer Entwicklungsumgebung aktiviert ist, und Ihnen hilft, häufig auftretende Fehler in Ihren Komponenten zu finden. Dies bietet die folgenden Vorteile:

  • Ihre Komponenten werden auf die Verwendung veralteter APIs geprüft
  • Die Komponenten werden erneut gerendert, um Komponenten zu finden, die ihr Verhalten beim zweiten Rendern unbeabsichtigt ändern
  • Es wird ein zusätzlicher Einrichtungs- und Bereinigungszyklus für alle Effekte in Ihrem Code erneut ausgeführt

Um den React Strict Mode zu aktivieren, fügen Sie der Datei .env die Umgebungsvariable JUTRO_REACT_STRICT_MODE=true hinzu.

Für bereits vorhandene Anwendungen ist der Strict Mode nicht standardmäßig aktiviert. Bei allen neuen Jutro-Apps, die aus einer Jutro-App-Vorlage erstellt werden, wird die Umgebungsvariable in der .env-Datei aktiviert.

Wenn JUTRO_REACT_STRICT_MODE=true in der .env-Datei im Stammverzeichnis einer Jutro-Anwendung festgelegt ist und die Anwendung in Nicht-Produktionsumgebungen im Entwicklermodus ausgeführt wird, wird in der Funktion start.js der Anwendung die folgende Prüfung ausgeführt:

const isReactStrictMode = process.env.JUTRO_REACT_STRICT_MODE;
reactRoot.render(
  isReactStrictMode ? (
    <StrictMode>{WrappedComponent}</StrictMode>
  ) : (
    WrappedComponent
  )
);

Wenn der React Strict Mode in einer Jutro-Anwendung aktiviert ist, wird die gesamte Anwendung so behandelt, als wäre sie von <StrictMode>-Tags umschlossen.