Configuración global\n

Introducción

La configuración global son datos de toda la aplicación que se almacenan de forma centralizada en el almacén global y a los que se puede acceder durante toda la vida útil de la aplicación. Una vez que se inicializa su aplicación (consulte Configuración inicial de la aplicación), la configuración se almacena globalmente y puede recuperar, actualizar y administrar valores en cualquier lugar de componentes, servicios, utilidades o clientes API.

En esta página se abordan las API para trabajar con la configuración global:

Archivos de configuración. Cómo estructurar y almacenar la configuración en su proyecto.
Variables de entorno. Cómo proporcionar una fuente alternativa para los valores de configuración que tengan prioridad sobre los archivos de configuración.
getConfigValue(). Recupere los valores de configuración con resolución de respaldo, verificando primero las variables de entorno y, a continuación, el almacén global.
loadConfiguration(). Cargue e inicialice la configuración (normalmente llamada durante la inicialización de la aplicación).
setConfiguration(). Actualice la configuración global mediante programación en tiempo de ejecución.
getConfiguration(). Acceda directamente a todo el objeto de configuración.

Utilice esta guía para implementar la configuración global en sus aplicaciones de Jutro.

La inicialización de la aplicación permite la configuración global

Durante la fase de inicialización, la aplicación carga la configuración en un almacén global mediante la función loadConfiguration(). Esto sucede una vez, al inicio:

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

Una vez completada la inicialización, puede acceder a esos valores almacenados y administrarlos en cualquier lugar de la aplicación.

Fuentes de la configuración

Los valores de configuración provienen de varias fuentes:

Almacén global. Objeto JavaScript en memoria que contiene su configuración. Se rellena llamando a loadConfiguration() con datos de sus archivos de configuración JSON como src/config/config.json.
Variables de entorno. Valores definidos en su archivo .env (con los prefijos REACT_APP_ o JUTRO_) que se cargan en process.env en tiempo de ejecución. La función getConfigValue() verifica process.env al recuperar valores.
Variables de implementación. Valores definidos en Jutro Web Apps, que se inyectan en el tiempo de ejecución y se pueden cargar en el almacén global con loadConfiguration(). Para obtener más información, consulte la documentación de Jutro Web Apps.

Las variables de entorno no rellenan el almacén global. En cambio, cuando llama a getConfigValue(), verifica process.env primero antes de buscar en el almacén global. Esto mantiene las variables de entorno separadas de la configuración de la aplicación, a la vez que les permite tener prioridad. Este comportamiento se puede revertir con JUTRO_NEW_CONFIG_LOADING_ORDER=true para verificar primero el almacén global. Consulte la sección Orden de carga de las variables de entorno para obtener detalles.

Uso de la configuración global para su aplicación

El método recomendado es centralizar la configuración en src/config/config.json. Este archivo único sirve como la ubicación estándar para todos los valores de configuración globales y se carga automáticamente durante la inicialización de la aplicación, una vez que esta se configura por primera vez.

Si hay razones específicas para separar la configuración en varios archivos, puede crear archivos JSON adicionales en el directorio src/config/ y cargarlos cuando sea necesario.

Cómo crear un archivo de configuración

Cree un archivo JSON en el directorio src/config/, por ejemplo src/config/config.json.

Agregue los valores de configuración al archivo:

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

Importe el archivo de configuración en el archivo startApp y cárguelo durante la inicialización:

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

loadConfiguration(appConfig);

Use los valores de su aplicación con una de las opciones disponibles:

getConfigValue (API disponible aquí)

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

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

getConfiguration (API disponible aquí)

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

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

Cómo agregar claves de configuración a un archivo de configuración existente

Requisito: la inicialización de la aplicación debe estar configurada. Consulte Configuración inicial de la aplicación para obtener más información.

Agregue su valor a src/config/config.json:

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

Use el valor de la aplicación:

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

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

Cómo importar archivos de configuración directamente

Note: Este método es una alternativa a la configuración global, no forma parte del sistema de configuración global. Los valores importados directamente no se almacenan en el almacén global y solo están disponibles cuando se importen.

Abra el archivo de configuración existente o cree un archivo JSON en el directorio src/config/, por ejemplo src/config/urlConfig.json.

Agregue el valor al archivo de configuración:

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

Use el valor de la aplicación:

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

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

Variables de entorno en la configuración

Las variables de entorno proporcionan una forma alternativa de establecer valores de configuración sin modificar los archivos del proyecto. Esto es útil para ajustes específicos de implementación o invalidaciones según el entorno.

Cuando se define una clave de configuración en una variable de entorno, esta automáticamente tiene prioridad sobre la misma clave en los archivos de configuración cuando llame a getConfigValue(). Las variables de entorno no actualizan su entorno real, solo afectan lo que getConfigValue() devuelve.

Para crear una variable de entorno:

Cree un archivo .env en la raíz de la aplicación Jutro.
Agregue el valor con un prefijo REACT_APP_, por ejemplo:
```
REACT_APP_JUTRO_LOGGER_LEVEL=DEBUG
```

Lea el valor de la aplicación:

const loggerLevel = process.env.JUTRO_LOGGER_LEVEL;

const loggerLevel = getConfigValue('loggerLevel');

Note: Si agrega SAFE_ENV=true, a su archivo .env, solo se permiten variables que comiencen con JUTRO_ o REACT_APP_. Esto respeta las prácticas con respecto a las variables de entorno en la aplicación React.

Invalidación de valores de configuración con variables de entorno

Puede usar variables de entorno para invalidar los valores de configuración sin modificar sus archivos de configuración. Esto es útil para diferentes entornos de implementación.

Por ejemplo, si el archivo de configuración contiene:

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

Y su archivo .env contiene:

REACT_APP_dashboardUrl=https://dev-dashboard.com

Cuando llame a getConfigValue(), la variable de entorno tiene prioridad:

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

Funciones de configuración

getConfigValue

Parámetros

pathobligatorio: Tipo
string
Descripción
The object path to the configuration value. Supports dot notation for nested values.
defaultValue: Tipo
boolean | string | object | number
Descripción
The default value returned if no value is found at the given path.

Uso

La función getConfigValue recupera los valores de configuración con resolución de respaldo. El orden de búsqueda cuando llama a getConfigValue(key) es:

Verifique los valores de las variables de entorno en process.env.REACT_APP_key (con puntos convertidos en guiones bajos).
Verifique process.env para determinar si la clave coincide exactamente.
Verifique la clave en el almacén global mediante el recorrido de propiedad anidada:
- Si la clave contiene puntos (p. ej., 'database.host'), recorre la estructura de objetos anidados.
- Si la clave es plana (p. ej., 'JUTRO_PC_CLOUD_API_URL'), recupérela como una propiedad exacta.
Utilice el valor predeterminado que usted proporcionó si ninguno de los anteriores contiene la clave.

Para uso básico con un valor simple, la función comprueba primero las variables de entorno (con el prefijo REACT_APP_) y, a continuación, vuelve al almacén global de configuración. Si ninguno de los dos existe, utiliza el valor predeterminado proporcionado.

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

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

Cuando utilice componentes de React, recupere los valores de configuración dentro de sus componentes para controlar el comportamiento en función de la configuración específica del entorno.

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

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

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

De forma predeterminada, las variables de entorno tienen prioridad sobre los valores del archivo de configuración. Habilite JUTRO_NEW_CONFIG_LOADING_ORDER=true para revertir este comportamiento para las configuraciones cargadas en tiempo de ejecución.

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

Proporcione siempre un valor predeterminado para las claves de configuración opcionales, a fin de asegurarse de que su aplicación tenga un comportamiento de respaldo razonable.

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

Acceso a los valores de configuración por coincidencia exacta de claves

Puede acceder a las claves planas por su nombre exacto. Esto funciona tanto para las variables de entorno como para los valores en el almacén global de configuración.

Desde el archivo .env (sin el prefijo REACT_APP_):

MY_CUSTOM_VAR=customValue

Desde el almacén global (por ejemplo, variables de implementación):

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

Accediendo a ambos:

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

Acceso a valores de configuración anidados

Utilice la notación de puntos para acceder a los valores de configuración anidados en su configuración. El comportamiento difiere entre las variables de entorno y los valores de configuración:

Variables de entorno: Los puntos se convierten en guiones bajos y tienen el prefijo REACT_APP_. Por ejemplo, getConfigValue('database.host') busca REACT_APP_DATABASE_HOST.
Valores de configuración: Los puntos se utilizan directamente para el recorrido de objetos anidados. Por ejemplo, getConfigValue('database.host') busca el valor en la ruta anidada database.host en su configuración.

Ejemplo con variables de entorno (archivo .env):

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

Ejemplo con config.json:

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

Acceso en código:

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

Las variables de entorno se verifican primero. Si existe REACT_APP_DATABASE_HOST, tiene prioridad sobre config.database.host. Utilice JUTRO_NEW_CONFIG_LOADING_ORDER=true para invertir esta prioridad.

loadConfiguration

Parámetros

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

Uso

La función loadConfiguration carga y almacena objetos de configuración de manera local, lo que admite la sustitución de parámetros de plantilla. Utilícela para inicializar la configuración de la aplicación al inicio.

Inicialice la configuración con el objeto de configuración personalizado y almacénelo para usarlo en toda la aplicación.

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

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

loadConfiguration(customConfig);

Utilice el argumento params para sustituir variables de plantilla en sus valores de configuración. Esto resulta útil para la configuración dinámica basada en parámetros específicos del entorno.

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

Combine loadConfiguration con getConfigValue para inicializar la configuración y, luego, recuperar valores específicos en toda la aplicación.

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

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

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

Note: Consulte la documentación de Jutro Web Apps para obtener detalles sobre cómo manejar variables de implementación y cargarlas en su configuración en tiempo de ejecución utilizando loadConfiguration.

Orden de carga de las variables de entorno

La función loadConfiguration se puede utilizar para establecer el valor de una variable de entorno en tiempo de ejecución, por ejemplo:

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

Sin embargo, los valores de las variables de entorno definidos en el archivo .env tienen prioridad sobre los establecidos por la función loadConfiguration. Esto sucede porque getConfigValue implementa un orden de resolución específico. Verifica las variables de entorno antes de verificar el objeto de configuración almacenado. Esto significa que puede establecer el valor de nuevas variables, pero cualquier variable de tiempo de compilación definida en su archivo .env no puede cambiar sus valores con esta función.

Para cambiar la prioridad de configuración, especifique JUTRO_NEW_CONFIG_LOADING_ORDER=true en su entorno. Con esta opción habilitada, el valor cargado con el método loadConfiguration utilizado en tiempo de ejecución tiene prioridad sobre el archivo .env.

setConfiguration

Parámetros

configobligatorio: Tipo
Record<string, any>
Descripción
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.

Uso

La función setConfiguration almacena un objeto de configuración en el espacio de nombres global. Por lo general, loadConfiguration llama internamente a esto, pero lo puede usar directamente cuando necesite actualizar la configuración global mediante programación.

La función setConfiguration almacena un objeto de configuración en el espacio de nombres global, lo que permite que todas las partes de la aplicación puedan acceder a él de manera global.

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'

Utilice setConfiguration para actualizar la configuración global en tiempo de ejecución. Esto es útil cuando la configuración debe cambiarse dinámicamente en función de las acciones del usuario o las condiciones de tiempo de ejecución.

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'

Tenga en cuenta que la copia superficial implica que los objetos anidados permanecerán como referencias. Si modifica las propiedades anidadas después de llamar a setConfiguration, esos cambios se reflejan en la configuración almacenada globalmente.

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 función getConfiguration no tiene parámetros y devuelve todo el objeto de configuración global que se cargó anteriormente.

Uso

Recupera todo el objeto de configuración global que se estableció a través de loadConfiguration o setConfiguration. Esto le proporciona acceso directo a la configuración sin procesar sin depender de la lógica de resolución getConfigValue.

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

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

Utilice getConfiguration cuando deba realizar operaciones personalizadas en todo el objeto de configuración, como filtrar o transformar valores con fines de depuración.

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

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

Acceda directamente a las propiedades de configuración anidadas utilizando la sintaxis de objetos de JavaScript, en lugar del formato de string de notación de puntos utilizado por getConfigValue.

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

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

Combine getConfiguration con setConfiguration para actualizar valores de configuración específicos conservando otros ajustes.

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

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

setConfiguration(updatedConfig);

Opciones de configuración adicionales

Modo estricto de React

El modo estricto de React es un componente nativo de React que ejecuta verificaciones adicionales cuando está habilitado en un entorno de desarrollo, lo que le ayuda a encontrar errores comunes en sus componentes. Ofrece los siguientes beneficios:

Comprueba los componentes para detectar cualquier uso de API obsoletas.
Vuelve a renderizar los componentes una vez más para intentar encontrar cualquier componente que cambie involuntariamente su comportamiento cuando se renderiza por segunda vez.
Vuelve a ejecutar un ciclo adicional de configuración y limpieza para detectar cualquier efecto en el código.

Para habilitar el modo estricto de React, en su archivo .env, agregue JUTRO_REACT_STRICT_MODE=true.

Las aplicaciones preexistentes no tendrán habilitado el modo estricto de forma predeterminada, sin embargo, cualquier aplicación nueva de Jutro creada a partir de una plantilla de aplicación de Jutro tendrá la variable de entorno habilitada en el archivo .env.

Si JUTRO_REACT_STRICT_MODE=true se establece en el archivo .env dentro de la raíz de una aplicación de Jutro y la aplicación se ejecuta en modo de desarrollador en entornos de no producción, la siguiente verificación se ejecuta en la función start.js de la aplicación:

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

Cuando el modo estricto de React está habilitado en una aplicación de Jutro, toda la aplicación se trata como si estuviera encapsulada en etiquetas <StrictMode>.

Configuración global\n

Introducción

La inicialización de la aplicación permite la configuración global

Fuentes de la configuración

Uso de la configuración global para su aplicación

Cómo crear un archivo de configuración

Cómo agregar claves de configuración a un archivo de configuración existente

Cómo importar archivos de configuración directamente

Variables de entorno en la configuración

Invalidación de valores de configuración con variables de entorno

Funciones de configuración

getConfigValue

Parámetros

`path`obligatorio

`defaultValue`

Uso

Acceso a los valores de configuración por coincidencia exacta de claves

Acceso a valores de configuración anidados

loadConfiguration

Parámetros

`config`

`params`

`baseConfig`obsoleto

Uso

Orden de carga de las variables de entorno

setConfiguration

Parámetros

`config`obligatorio

Uso

getConfiguration

Uso

Opciones de configuración adicionales

Modo estricto de React

Introducción​

La inicialización de la aplicación permite la configuración global​

Fuentes de la configuración​

Uso de la configuración global para su aplicación​

Cómo crear un archivo de configuración​

Cómo agregar claves de configuración a un archivo de configuración existente​

Cómo importar archivos de configuración directamente​

Variables de entorno en la configuración​

Invalidación de valores de configuración con variables de entorno​

Funciones de configuración​

getConfigValue​

Parámetros​

pathobligatorio​

defaultValue​

Uso​

Acceso a los valores de configuración por coincidencia exacta de claves​

Acceso a valores de configuración anidados​

loadConfiguration​

Parámetros​

config​

params​

baseConfigobsoleto​

Uso​

Orden de carga de las variables de entorno​

setConfiguration​

Parámetros​

configobligatorio​

Uso​

getConfiguration​

Uso​

Opciones de configuración adicionales​

Modo estricto de React​

Introducción

La inicialización de la aplicación permite la configuración global

Fuentes de la configuración

Uso de la configuración global para su aplicación

Cómo crear un archivo de configuración

Cómo agregar claves de configuración a un archivo de configuración existente

Cómo importar archivos de configuración directamente

Variables de entorno en la configuración

Invalidación de valores de configuración con variables de entorno

Funciones de configuración

getConfigValue

Parámetros

`path`obligatorio

`defaultValue`

Uso

Acceso a los valores de configuración por coincidencia exacta de claves

Acceso a valores de configuración anidados

loadConfiguration

Parámetros

`config`

`params`

`baseConfig`obsoleto

Uso

Orden de carga de las variables de entorno

setConfiguration

Parámetros

`config`obligatorio

Uso

getConfiguration

Uso

Opciones de configuración adicionales

Modo estricto de React