Configuration globale

Introduction

La configuration globale correspond aux données à l’échelle de l’application stockées de manière centralisée dans le magasin global et accessibles tout au long de la durée de vie de votre application. Une fois votre application initialisée (voir Configuration de l’application), la configuration est stockée globalement et vous pouvez récupérer, mettre à jour et gérer les valeurs n’importe où dans les composants, les services, les utilitaires ou les API clients.

Cette page présente les API permettant d’utiliser la configuration globale :

Fichiers de configuration : comment structurer et stocker la configuration dans votre projet.
Variables d’environnement : comment fournir une source alternative pour les valeurs de configuration prioritaire sur les fichiers de configuration.
getConfigValue() : récupérer les valeurs de configuration avec une résolution de secours, en vérifiant d’abord les variables d’environnement, puis le magasin global.
loadConfiguration() : charger et initialiser la configuration (généralement appelée lors de l’initialisation de l’application).
setConfiguration() : mettre à jour la configuration globale par programmation au moment de l’exécution.
getConfiguration() : accès direct à l’ensemble de l’objet de configuration.

Utilisez ce guide pour implémenter la configuration globale dans vos applications Jutro.

L’initialisation de l’application permet une configuration globale

Au cours de la phase d’initialisation, votre application charge la configuration dans un magasin global à l’aide de la fonction loadConfiguration(). Cela se produit une fois, au démarrage :

// 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, {
  /* ... */
});

Une fois l’initialisation terminée, vous pouvez accéder à ces valeurs stockées et les gérer n’importe où dans votre application.

Sources de configuration

Les valeurs de configuration proviennent de plusieurs sources :

Magasin global : objet JavaScript en mémoire qui contient votre configuration. Il est rempli en appelant loadConfiguration() avec les données de vos fichiers de configuration JSON, comme src/config/config.json.
Variables d’environnement : valeurs définies dans votre fichier .env (avec le préfixe REACT_APP_ ou JUTRO_) chargées dans process.env au moment de l’exécution. La fonction getConfigValue() vérifie process.env lors de la récupération des valeurs.
Variables de déploiement : valeurs définies dans Jutro Web Apps, qui sont injectées au moment de l’exécution et qui peuvent être chargées dans le magasin global avec loadConfiguration(). Pour en savoir plus, reportez-vous à la documentation sur Jutro Web Apps.

Les variables d’environnement ne remplissent pas le magasin global. Lorsque vous appelez getConfigValue(), il vérifie d'abord process.env avant de regarder dans le magasin global. Cela permet de séparer les variables d’environnement de la configuration de votre application tout en leur permettant d’être prioritaires. Ce comportement peut être inversé avec JUTRO_NEW_CONFIG_LOADING_ORDER=true pour vérifier d’abord le magasin global. Pour en savoir plus, reportez-vous à Ordre de chargement des variables d’environnement.

Utiliser la configuration globale pour votre application

L’approche recommandée consiste à centraliser votre configuration dans src/config/config.json. Ce fichier unique sert d’emplacement standard pour toutes les valeurs de configuration globales et est automatiquement chargé lors de l’initialisation de l’application, une fois qu’elle est configurée.

S’il existe des raisons spécifiques de séparer la configuration en plusieurs fichiers, vous pouvez créer des fichiers JSON supplémentaires dans le répertoire src/config/ et les charger si nécessaire.

Créer un fichier de configuration

Créez un fichier JSON dans le répertoire src/config/, par exemple src/config/config.json.

Ajoutez vos valeurs de configuration au fichier :

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

Importez le fichier de configuration dans votre fichier startApp et chargez-le lors de l’initialisation :

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

loadConfiguration(appConfig);

Utilisez les valeurs de votre application à l’aide de l’une des options disponibles :

getConfigValue (API disponible ici)

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

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

getConfiguration (API disponible ici)

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

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

Ajouter des clés de configuration au fichier de configuration existant

Prérequis : l’initialisation de votre application doit être configurée. Pour en savoir plus, reportez-vous à Configuration de l’application.

Ajoutez votre valeur à src/config/config.json :

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

Utilisez la valeur dans votre application :

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

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

Importer directement les fichiers de configuration

Note: Cette approche est une alternative à la configuration globale et ne fait pas partie du système de configuration globale. Les valeurs importées directement ne sont pas stockées dans le magasin global et ne sont disponibles que là où elles sont importées.

Ouvrez un fichier de configuration existant ou créez un fichier JSON dans le répertoire src/config/, par exemple src/config/urlConfig.json.
Ajoutez votre valeur dans le fichier de configuration :
```
{
  "dashboardUrl": "https://example-dashboard.com"
}
```

Utilisez la valeur dans votre application :

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

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

Variables d’environnement dans la configuration

Les variables d’environnement constituent une autre façon de définir des valeurs de configuration sans modifier vos fichiers de projet. Ceci est utile pour les paramètres spécifiques au déploiement ou les remplacements par environnement.

Lorsque vous définissez une clé de configuration dans une variable d’environnement, elle prend automatiquement la priorité sur la même clé dans vos fichiers de configuration lorsque vous appelez getConfigValue(). La variable d’environnement ne met pas à jour votre environnement réel, elle affecte uniquement ce que getConfigValue() renvoie.

Pour créer une variable d’environnement :

Créez un fichier .env à la racine de votre application Jutro.
Ajoutez la valeur avec un préfixe REACT_APP_, par exemple :
```
REACT_APP_JUTRO_LOGGER_LEVEL=DEBUG
```

Lisez la valeur dans votre application :

const loggerLevel = process.env.JUTRO_LOGGER_LEVEL;

ou :

const loggerLevel = getConfigValue('loggerLevel');

Note: Si vous ajoutez SAFE_ENV=true, dans votre fichier .env, seules les variables commençant par JUTRO_ ou REACT_APP_ sont autorisées. Ceci est conforme aux pratiques relatives aux variables d'environnement dans l'application React.

Remplacer les valeurs de configuration par des variables d’environnement

Vous pouvez utiliser des variables d’environnement pour remplacer les valeurs de configuration sans modifier vos fichiers de configuration. Ceci est utile pour différents environnements de déploiement.

Par exemple, si votre fichier de configuration contient :

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

Et que votre fichier .env contient :

REACT_APP_dashboardUrl=https://dev-dashboard.com

Ensuite, lorsque vous appelez getConfigValue(), la variable d’environnement devient prioritaire :

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

Fonctions de configuration

getConfigValue

Paramètres

pathobligatoire: Type
string
Description
The object path to the configuration value. Supports dot notation for nested values.
defaultValue: Type
boolean | string | object | number
Description
The default value returned if no value is found at the given path.

Utilisation

La fonction getConfigValue récupère les valeurs de configuration avec une résolution d'action de secours. L’ordre de recherche lorsque vous appelez getConfigValue(key) est le suivant :

Recherchez dans process.env.REACT_APP_key les valeurs de variables d’environnement (avec les points convertis en traits de soulignement).
Recherchez dans process.env la correspondance exacte des clés.
Vérifiez le magasin global de la clé à l’aide d'un parcours de propriétés imbriquées :
- Si la clé contient des points (par exemple, 'database.host'), parcourez la structure d’objets imbriqués.
- Si la clé est fixe (par exemple, 'JUTRO_PC_CLOUD_API_URL'), récupérez-la en tant que propriété exacte.
Utilisez la valeur par défaut que vous avez indiquée, si aucune des valeurs ci-dessus ne contient la clé.

Pour une utilisation basique avec une valeur simple, la fonction vérifie d’abord les variables d’environnement (avec le préfixe REACT_APP_), puis revient au magasin global de configuration. Si aucun des deux n’existe, il utilise la valeur par défaut fournie.

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

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

Lorsque vous utilisez des composants React, récupérez les valeurs de configuration au sein de vos composants pour contrôler le comportement en fonction des paramètres spécifiques à l’environnement.

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

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

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

Par défaut, les variables d’environnement sont prioritaires sur les valeurs du fichier de configuration. Activez cette option JUTRO_NEW_CONFIG_LOADING_ORDER=true pour inverser ce comportement pour les configurations chargées lors de l’exécution.

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

Fournissez toujours une valeur par défaut pour les clés de configuration facultatives afin de garantir que votre application a un comportement de secours approprié.

const port = getConfigValue('server.port', 3000);
const isDev = getConfigValue('environment.isDevelopment', false);

Accès aux valeurs de configuration par correspondance de clé exacte

Vous pouvez accéder aux clés fixes par leur nom exact. Cela fonctionne à la fois pour les variables d’environnement et pour les valeurs du magasin global de configuration.

À partir du fichier .env (sans préfixe REACT_APP_) :

MY_CUSTOM_VAR=customValue

À partir du magasin global (par exemple, les variables de déploiement) :

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

Accéder aux deux :

// 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

Accéder aux valeurs de configuration imbriquées

Utilisez la notation par points pour accéder aux valeurs de configuration imbriquées dans votre configuration. Le comportement diffère selon s'il s'agit de variables d’environnement et de valeurs de configuration :

Variables d’environnement : les points sont convertis en traits de soulignement et précédés du préfixe REACT_APP_. Par exemple, getConfigValue('database.host') recherche REACT_APP_DATABASE_HOST.
Valeurs de configuration : les points sont utilisés directement pour le parcours d’objets imbriqués. Par exemple, getConfigValue('database.host') recherche la valeur au niveau du chemin database.host imbriqué dans votre configuration.

Exemple avec des variables d’environnement (fichier .env) :

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

Exemple avec config.json :

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

Accès dans le 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

Les variables d’environnement sont vérifiées en premier. Si REACT_APP_DATABASE_HOST existe, elle est prioritaire sur config.database.host. Utilisez JUTRO_NEW_CONFIG_LOADING_ORDER=true pour inverser cette priorité.

loadConfiguration

Paramètres

config: Type
Record<string, any>
Description
Configuration object containing custom configuration settings to be merged with the base configuration.
params: Type
Record<string, any>
Description
Map of parameters to be used in mustache template substitutions within the configuration values.
baseConfigobsolète: Type
Record<string, any>
Description
Base configuration object merged by function with the provided config. Defaults to defaultConfig if not specified.

Utilisation

La fonction loadConfiguration charge et stocke les objets de configuration globalement, ce qui prend en charge la substitution de paramètres de modèle. Utilisez-la pour initialiser la configuration de votre application au démarrage.

Initialisez la configuration avec votre objet de configuration personnalisé et stockez-la pour l’utiliser dans toute votre application.

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

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

loadConfiguration(customConfig);

Utilisez l’argument params pour remplacer des variables de modèle dans vos valeurs de configuration. Ceci est utile pour une configuration dynamique basée sur des paramètres spécifiques à l’environnement.

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' }

Combinez loadConfiguration avec getConfigValue pour initialiser votre configuration, puis récupérer des valeurs spécifiques dans l’ensemble de votre application.

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

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

const dbHost = getConfigValue('database.host');

Note: Reportez-vous à la documentation de Jutro Web Apps pour en savoir plus sur la gestion des variables de déploiement et leur chargement dans votre configuration au moment de l’exécution à l’aide de loadConfiguration.

Ordre de chargement des variables d'environnement

La fonction loadConfiguration peut être utilisée pour définir la valeur d'une variable d'environnement au moment de l'exécution, par exemple :

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

Toutefois, les valeurs de variables d'environnement définies dans votre fichier .env sont prioritaires sur celles définies par la fonction loadConfiguration. Cela se produit car getConfigValue met en œuvre un ordre de résolution spécifique. Elle vérifie les variables d’environnement avant de vérifier l’objet de configuration stocké. Cela signifie que vous pouvez définir la valeur de nouvelles variables, mais que les valeurs des variables défrinies au moment de la compilation dans votre fichier .env ne peuvent pas être modifiées avec cette fonction.

Pour modifier la priorité de configuration, vous pouvez spécifier JUTRO_NEW_CONFIG_LOADING_ORDER=true dans votre environnement. Lorsque cette option est activée, la valeur chargée avec la méthode loadConfiguration utilisée lors de l'exécution est prioritaire sur votre fichier .env.

setConfiguration

Paramètres

configobligatoire: Type
Record<string, any>
Description
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.

Utilisation

La fonction setConfiguration stocke un objet de configuration dans l’espace de noms global. Cette méthode est généralement appelée en interne par loadConfiguration, mais vous pouvez l’utiliser directement lorsque vous devez mettre à jour la configuration globale par programmation.

La fonction setConfiguration stocke un objet de configuration dans l’espace de noms global, ce qui le rend accessible globalement à toutes les parties de votre application.

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'

Utilisez setConfiguration pour mettre à jour la configuration globale au moment de l’exécution. Ceci est utile lorsque la configuration doit être modifiée dynamiquement en fonction des actions de l’utilisateur ou des conditions d’exécution.

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'

Gardez à l’esprit qu’une copie superficielle implique que les objets imbriqués restent comme références. Si vous modifiez les propriétés imbriquées après avoir appelé setConfiguration, ces modifications sont répercutées dans la configuration stockée globalement.

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

La fonction getConfiguration n’a pas de paramètres et renvoie l’intégralité de l’objet de configuration global qui a été chargé précédemment.

Utilisation

Récupère l’intégralité de l’objet de configuration global qui a été défini via loadConfiguration ou setConfiguration. Cela vous donne un accès direct à la configuration brute sans dépendre de la logique de résolution getConfigValue.

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

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

Utilisez getConfiguration lorsque vous devez effectuer des opérations personnalisées sur l’intégralité de l’objet de configuration, telles que le filtrage ou la transformation de valeurs à des fins de débogage.

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

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

Accédez aux propriétés de configuration imbriquées directement à l’aide de la syntaxe d’objet JavaScript au lieu du format de chaîne de notation par points utilisé par getConfigValue.

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

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

Combinez getConfiguration avec setConfiguration pour mettre à jour des valeurs de configuration spécifiques tout en conservant les autres paramètres.

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

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

setConfiguration(updatedConfig);

Options de configuration supplémentaires

Mode React Strict

Le mode React Strict est un composant React natif qui exécute des vérifications supplémentaires lorsqu'il est activé dans un environnement de développement, ce qui vous aide à trouver les bogues couramment rencontrés dans vos composants. Il offre les avantages suivants :

Il vérifie toute utilisation d'API obsolètes par vos composants
Il effectue un nouveau rendu de vos composants une fois de plus pour essayer de trouver les composants qui modifient involontairement leur comportement lorsqu'ils sont affichés une seconde fois
Il réexécute un cycle de configuration et de nettoyage supplémentaire pour tous les effets de votre code

Pour activer le mode React Strict, dans votre fichier .env, ajoutez JUTRO_REACT_STRICT_MODE=true.

Le mode strict n'est pas activé par défaut pour les applications préexistantes, mais la variable d'environnement sera activée dans le fichier .env pour toutes les nouvelles applications Jutro créées à partir d'un modèle d'application Jutro.

Si JUTRO_REACT_STRICT_MODE=true est défini dans le fichier .env à l'intérieur de la racine d'une application Jutro et si l'application est exécutée en mode développeur dans des environnements hors production, la vérification suivante s'exécute dans la fonction start.js de l'application :

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

Lorsque le mode React Strict est activé dans une application Jutro, l'application entière est traitée comme si elle était encapsulée dans des balises <StrictMode>.

Configuration globale

Introduction

L’initialisation de l’application permet une configuration globale

Sources de configuration

Utiliser la configuration globale pour votre application

Créer un fichier de configuration

Ajouter des clés de configuration au fichier de configuration existant

Importer directement les fichiers de configuration

Variables d’environnement dans la configuration

Remplacer les valeurs de configuration par des variables d’environnement

Fonctions de configuration

getConfigValue

Paramètres

`path`obligatoire

`defaultValue`

Utilisation

Accès aux valeurs de configuration par correspondance de clé exacte

Accéder aux valeurs de configuration imbriquées

loadConfiguration

Paramètres

`config`

`params`

`baseConfig`obsolète

Utilisation

Ordre de chargement des variables d'environnement

setConfiguration

Paramètres

`config`obligatoire

Utilisation

getConfiguration

Utilisation

Options de configuration supplémentaires

Mode React Strict

Introduction​

L’initialisation de l’application permet une configuration globale​

Sources de configuration​

Utiliser la configuration globale pour votre application​

Créer un fichier de configuration​

Ajouter des clés de configuration au fichier de configuration existant​

Importer directement les fichiers de configuration​

Variables d’environnement dans la configuration​

Remplacer les valeurs de configuration par des variables d’environnement​

Fonctions de configuration​

getConfigValue​

Paramètres​

pathobligatoire​

defaultValue​

Utilisation​

Accès aux valeurs de configuration par correspondance de clé exacte​

Accéder aux valeurs de configuration imbriquées​

loadConfiguration​

Paramètres​

config​

params​

baseConfigobsolète​

Utilisation​

Ordre de chargement des variables d'environnement​

setConfiguration​

Paramètres​

configobligatoire​

Utilisation​

getConfiguration​

Utilisation​

Options de configuration supplémentaires​

Mode React Strict​

Introduction

L’initialisation de l’application permet une configuration globale

Sources de configuration

Utiliser la configuration globale pour votre application

Créer un fichier de configuration

Ajouter des clés de configuration au fichier de configuration existant

Importer directement les fichiers de configuration

Variables d’environnement dans la configuration

Remplacer les valeurs de configuration par des variables d’environnement

Fonctions de configuration

getConfigValue

Paramètres

`path`obligatoire

`defaultValue`

Utilisation

Accès aux valeurs de configuration par correspondance de clé exacte

Accéder aux valeurs de configuration imbriquées

loadConfiguration

Paramètres

`config`

`params`

`baseConfig`obsolète

Utilisation

Ordre de chargement des variables d'environnement

setConfiguration

Paramètres

`config`obligatoire

Utilisation

getConfiguration

Utilisation

Options de configuration supplémentaires

Mode React Strict