Anwendungseinrichtung

Einführung

Dies ist eine Referenz für die Initialisierung einer Jutro-Anwendung. Hier erfahren Sie, wie Sie eine Initialisierungsdatei (üblicherweise mit dem Namen startApp.ts oder startApp.js) erstellen, wie Sie die Anwendung mit der Funktion start() einrichten und sie mit zusätzlichen Startfunktionen erweitern.

Jutro bietet ein erweitertes System zur Anwendungsinitialisierung, das Folgendes umfasst:

• Vollständige Unterstützung für Internationalisierung und Lokalisierung beim Laden von Nachrichten
• Integration von Theme-Systemen mit anpassbaren Stilen
• Fehlerbehandlung durch Fehlergrenzen
• Clientseitiges Routing mit Browserverlauf
• Gebietsschemaverwaltung über den Globalisierungsspeicher
• Toast-Benachrichtigungen und Verwaltung von modalen Fenstern
• Integration von Authentifizierung und Autorisierung
• Integrierte Funktionen zur Barrierefreiheit

Zur besseren Orientierung in diesem System finden Sie auf dieser Seite folgende Informationen:

• Vollständige API-Referenz für die Funktion start() zusammen mit Beispielen
• Das Muster für die startApp-Initialisierungsdatei und Richtlinien zu ihrer Strukturierung
• Praktische Initialisierungsbeispiele für gängige Szenarios
• Erweiterung der Initialisierung um zusätzliche Services, Zustandsverwaltung und Startlogik

Note: Informationen zum Laden und Abrufen von Konfigurationswerten während der gesamten Laufzeit Ihrer Anwendung finden Sie auf der Seite Globale Konfiguration. Diese Seite behandelt die Konfiguration während der Initialisierungsphase.

Die start()-Funktion

Die start()-Funktion initialisiert und rendert Ihre Jutro-Anwendung mit allen erforderlichen Kontextanbietern für Routing, Authentifizierung, Fehlergrenzen, Internationalisierung und mehr. Die start()-Funktion erfordert zwei Parameter:

start(Main, launchProps);

• Main: Ihre App-Komponente, die zum Hauptinhalt der Anwendung wird.
• launchProps: Ein Objekt mit Eigenschaften, das die Initialisierung und das Verhalten der Anwendung konfiguriert.

start(Jutro, {
  // Launch and initialization settings
  rootId: 'root',
  config: [config],

  // Application structure and behavior
  messageLoader: loadMessages,
  appName: 'Jutro App',
  routerBasename: '/app',
});

Importanweisung

import { start } from '@jutro/app';

Note: start() kann auch aus dem Paket @jutro/micro-frontends für Micro Frontend-Anwendungen importiert werden. Verfügt über eine zusätzliche mfeData-Eigenschaft. Weitere Informationen finden Sie in der Dokumentation zu Micro Frontends.

Anwendungsstartkonfiguration

Diese Eigenschaften steuern das grundlegende Startverhalten der Anwendung. Sie definieren, wo die Anwendung im DOM eingebunden wird, laden die Konfiguration, initialisieren Dienste und passen den Ladevorgang beim Start an. Diese Einstellungen werden direkt von der start()-Funktion verarbeitet, bevor die Anwendung gerendert wird.

appDescriptionerforderlich

Typ

IntlMessageShape

Beschreibung

Description of the application. Used for metadata and display purposes, such as in browser titles, accessibility labels, and application information.

rootIderforderlich

Typ

string

Beschreibung

The ID of the HTML element in public/index.html where the application is mounted. The React app renders within this element.

config

Typ

Array<Record<string, unknown>>

config

Typ

Record<string, unknown>

Beschreibung

Main configuration object with application settings. Becomes the first parameter of loadConfiguration().

params

Typ

Record<string, string>

Beschreibung

Template parameters for mustache substitution in configuration values. Becomes the second parameter of loadConfiguration().

baseConfigVerworfen

Typ

Record<string, unknown>

Beschreibung

Base configuration to merge with main config. Becomes the third parameter of loadConfiguration().

Beschreibung

Configuration array with up to 3 objects passed as arguments to loadConfiguration(config, params, baseConfig). Objects are spread as separate parameters.

disableThemeProvider

Typ

boolean

Beschreibung

Flag to disable the ThemeProvider wrapper. If true, the application renders without theme context.

identifierPrefix

Typ

string

Beschreibung

Prefix for React identifiers passed to ReactDOMClient.createRoot(). Helps avoid conflicts in multi-app setups.

onInit

Typ

() => void

Beschreibung

Callback function triggered immediately during start() initialization, before DOM rendering. Useful for any initialization logic that needs to be performed, for example loading a required service.

onRender

Typ

() => void

Beschreibung

Callback function triggered after the application component is rendered. Executed via useEffect in the render wrapper.

themeConfig

Typ

ThemeConfig

Beschreibung

Initial theme configuration passed to ThemeProvider. Defines colors, fonts, and other visual settings.

themeProviderProps

Typ

ThemeProviderProps

Beschreibung

Additional properties passed to the ThemeProvider component wrapper. Allows customization of theme behavior.

trackingConfig

Typ

TrackingConfig

Beschreibung

Tracking configuration for analytics. Used to initialize Datadog and Google Analytics with whitelist and dictionary settings.

Struktur der Kernanwendung

Diese Eigenschaften konfigurieren die Hauptstruktur und die grundlegenden Funktionen der Anwendung. Sie definieren, welche Komponente als Hauptanwendung gerendert werden soll, enthalten wichtige Metadaten, konfigurieren die Fehlerbehandlung für unerfasste Ausnahmen und aktivieren Kontextanbieter für die Zustandsverwaltung und Funktionsintegration.

appNameerforderlich

Typ

IntlMessageShape

Beschreibung

The name of the application. Used for display and internationalization purposes.

errorBoundary

Typ

React.ComponentClass<ErrorBoundaryProps>

Beschreibung

Custom error boundary component for the application. Handles uncaught errors and displays fallback UI. Replaces the default ErrorBoundary from @jutro/components.

Standardwert

`ErrorBoundary` from `@jutro/components`

mfeData

Typ

{ scopeName: string }

Beschreibung

Micro frontend data passed to the application. Contains scope name for micro frontend identification. Only used in micro frontend contexts. You can pass this property to start() function only if it is imported from @jutro/micro-frontends package.

onError

Typ

ErrorBoundaryProps['onError']

Beschreibung

Callback function triggered when an error occurs. Provides error details and error information.

rootHOCs

Typ

RootHOCsType

Beschreibung

Function or array of functions that wrap your application to pass context down into it. These HOCs work differently than traditional React HOCs, because they take a React.ReactNode as input rather than a component class. For additional details see this section.

Routing-Konfiguration

Diese Eigenschaften verwalten das clientseitige Routing, den Navigationsverlauf, die Routerkonfiguration und die Ereignisbehandlung von modalen Fenstern. Sie steuern, wie Routenänderungen in der Anwendung verarbeitet werden, richten benutzerdefinierte Router ein, verwalten modale Dialoge und integrieren die Analyseverfolgung für Navigationsereignisse.

modalEmitter

Typ

ModalNextEmitterType

Beschreibung

Custom modal emitter instance for managing modal dialogs across the application. Use this when you need to set up event listeners or integrations before the application starts.

Standardwert

`new ModalNextEmitter()`

Router

Typ

ComponentType<BrowserRouterProps> | ComponentType<MemoryRouterProps>

Beschreibung

Custom router component for handling navigation. Must accept the same props as BrowserRouter or MemoryRouter. Use this to override the default router selection, add custom routing behavior (like analytics tracking), or force a specific router type for your environment. If not passed, BrowserRouter is used in browser environments and MemoryRouter is used in test environments.

routerBasename

Typ

string

Beschreibung

Base URL for all locations in the router. Used when serving the app from a subdirectory instead of the root. A properly formatted basename should have a leading slash, but no trailing slash. It overrides the JUTRO_ROUTER_BASENAME environment variable or REACT_APP_JUTRO_ROUTER_BASENAME in the .env file if they are set.

Standardwert

''

routerHistory

Typ

RouterProps['history']

Beschreibung

Custom history object for programmatic navigation and route management. Use this when you need to set up navigation tracking, implement custom navigation guards, perform programmatic navigation before app startup, or integrate with analytics. If not passed, BrowserHistory is used in browser environments and MemoryHistory is used in test environments.

trackingCallback

Typ

RouteTrackerProps['track']

Beschreibung

Callback function for tracking route changes and analytics. Use this when you need to integrate with analytics platforms, track user navigation patterns, monitor page views, or implement custom route-based logging. Called on every route change with location and action parameters.

Globalisierung

Mit diesen Eigenschaften werden die Globalisierung (g11n), Internationalisierung (i18n) und Lokalisierung (l10n) der Anwendung konfiguriert. Sie verwalten das Laden von Nachrichten, Spracheinstellungen, Gebietsschemaeinstellungen und steuern, wie internationalisierter Text in der Anwendung gerendert wird.

coreMessageLoader

Typ

LoaderType

Beschreibung

Function for loading Jutro's built-in core messages for internationalization. Takes a locale string (for example, 'en', 'es') and returns a Record<string, string> with core Jutro component messages and labels. If not provided, defaults to a function that logs warnings and returns an empty object, meaning Jutro components use their built-in English messages. Use this when you need to customize or translate Jutro's built-in component labels (buttons, form validation messages, etc.), load core messages from external sources, or provide enhanced translations for Jutro's default UI text.

g11nStore

Typ

G11nStore

Beschreibung

Store for globalization settings. Includes locale and language preferences.

intlTextComponent

Typ

IntlConfig['textComponent']

Beschreibung

HTML tag to wrap internationalized messages inside of, such as 'span', 'div', or 'p'. Affects how React Intl's <FormattedMessage> and other formatting components render their output. By default, React.Fragment is used, which renders text without any wrapper element. Use this when you need consistent HTML structure for all i18n text across your application, require specific semantic elements for accessibility, or need to integrate with CSS frameworks that expect particular HTML structures.

messageLoader

Typ

LoaderType

Beschreibung

Function for loading application-specific messages for internationalization. Takes a locale string (for example, 'en', 'es') and returns a Record<string, string> with message keys and translated values. If not provided, defaults to a function that logs warnings and returns an empty object, meaning your app won't have internationalized messages. Use this when you want to load messages from different sources (files, APIs, CDNs), implement custom fallback logic for unsupported locales, or organize messages in non-standard file structures.

Authentifizierungskonfiguration

Diese Eigenschaften konfigurieren das Authentifizierungsverhalten und die Fehlerbehandlung der Anwendung. Sie steuern benutzerdefinierte Authentifizierungsanbieter und Fehleranzeigekomponenten und legen fest, ob die Authentifizierung auf Anwendungsebene aktiviert ist.

authComponent

Typ

React.ComponentType

Beschreibung

Custom authentication provider component for handling authentication. By default, Jutro uses the built-in AuthProvider from @jutro/auth which provides standard authentication functionality. Use this when you need custom authentication flows, want to integrate with existing authentication infrastructure, or need mock authentication for development/testing.

authErrorComponent

Typ

AuthRouteProps['authErrorComponent']

Beschreibung

Custom error component to display when authentication errors occur. This component receives one prop: error (of type AuthError | undefined) containing the authentication error details. Use this to customize the authentication error display, or integrate error tracking with analytics platforms.

Standardwert

`AuthErrorPage` from `@jutro/app`

disableAuthErrorsHandling

Typ

boolean

Beschreibung

Flag to disable authentication error handling.

disableAuthForApplicationRoot

Typ

boolean

Beschreibung

Flag to disable authentication for the application root. If true, application root will not be wrapped with secure route handlers.

UI-Funktionen und Benutzererfahrung

Diese Eigenschaften konfigurieren Funktionen der Benutzeroberfläche und Präsentationsaspekte der Anwendung. Sie verwalten wesentliche UI-Funktionen wie Benachrichtigungen, modale Fenster, Ladestatus und Funktionen zur Barrierefreiheit, die die Benutzererfahrung verbessern.

disableModalProvider

Typ

boolean

Beschreibung

Flag to disable the ModalProvider wrapper around the application. By default, Jutro wraps your application with a ModalProvider to manage modal dialogs. Use this when you want to provide your own modal management system or integrate with a third-party modal library.

disableToastProvider

Typ

boolean

Beschreibung

Flag to disable the ToastProvider wrapper around the application. By default, Jutro wraps your application with a ToastProvider to enable toast notifications throughout your app. Use this when you want to provide your own toast notification system or integrate with a third-party notification library.

hideSkipNavigation

Typ

boolean

Beschreibung

Flag to hide the skip navigation link for accessibility. By default, Jutro includes a skip navigation link to help keyboard and screen reader users quickly navigate to main content. Use this when your application implements its own skip navigation mechanism.

loaderComponent

Typ

React.ElementType

Beschreibung

The component for wrapping the main component and presenting a loader UI when the app is loading. Replaces the default loader. Use this when you want to customize the loading experience, implement custom loading animations, or show different loader variants based on application state.

Standardwert

`Loader` from @jutro/components

mainComponentProps

Typ

Record<string, unknown>

Beschreibung

Additional props to pass to the main application component. These props are spread and passed directly to your main component as React component props. Use this when you need to pass custom configuration, event handlers, or data to your main application component without modifying the component itself.

modalFunctions

Typ

ModalFunctions

Beschreibung

Custom modal functions for managing modal behavior. Allows you to provide custom functions for opening, closing, and managing modal dialogs. Use this when you need to customize modal lifecycle behavior, implement modal state persistence, integrate with analytics platforms for modal events, or add custom validation before opening or closing modals.

toastTrigger

Typ

ToastTrigger

Beschreibung

Custom toast trigger function for displaying notifications. By default, Jutro uses the built-in toast trigger from @jutro/components. Use this when you need custom notification behavior, want to integrate with external notification systems, implement custom toast styling or animations, or need to add custom logging or analytics to toast events.

Initialisieren der Anwendung

Um eine Jutro-Anwendung zu initialisieren, erstellen Sie eine startApp.ts-Datei (oder startApp.js-Datei). Diese Datei wird herkömmlich importiert und über Ihren Webpack-Einstiegspunkt (src/index.ts) aufgerufen.

Note: Die Jutro Starter-Vorlage enthält diese Datei in vorkonfigurierter Form. Wenn Sie eine neue Anwendung von Grund auf erstellen, verwenden Sie die folgenden Beispiele als Ausgangspunkt.

Beispiel für eine einfache Initialisierung

Hier die minimale Konfiguration, die zur Initialisierung einer Jutro-Anwendung erforderlich ist:

src/startApp.js

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

import { Jutro } from './app/App';
import appConfig from './config/config.json';
import messages from './app/App.messages';
import { loadAppMessages, loadCoreMessages } from './messagesLoaders';

// Load configuration before starting the app
loadConfiguration(appConfig);

// Export the startApp function
export const startApp = (): void => {
  // Initialize the application
  start(Jutro, {
    rootId: 'root',
    messageLoader: loadAppMessages,
    coreMessageLoader: loadCoreMessages,
    appName: messages.appName,
    appDescription: messages.appDescription,
  });
};

Initialisierung für Micro Frontend-Anwendungen

Beim Erstellen von Micro Frontend-Apps erhält startApp den Wert mfeData, der den Shell-Kontext enthält:

src/startApp.js

import '@jutro/theme';
import './styles/index.scss';

import { MfeData, start } from '@jutro/micro-frontends';
import { loadConfiguration } from '@jutro/config';

import { Jutro } from './app/App';
import appConfig from './config/config.json';
import messages from './app/App.messages';
import { loadAppMessages, loadCoreMessages } from './messagesLoaders';

loadConfiguration(appConfig);

export const startApp = (mfeData?: MfeData): void => {
  start(Jutro, {
    rootId: 'root',
    messageLoader: loadAppMessages,
    coreMessageLoader: loadCoreMessages,
    appName: messages.appName,
    appDescription: messages.appDescription,
    mfeData, // Pass shell context to the app
  });
};

Strategien zum Laden von Konfigurationen

Es gibt zwei Ansätze zum Laden von Konfigurationen in Ihrer Jutro-Anwendung: explizites Laden über loadConfiguration() vor dem Aufrufen von start() oder Übergeben der config-Eigenschaft an start(). Jeder Ansatz eignet sich für unterschiedliche Anwendungsfälle. Es ist wichtig zu verstehen, wann welcher Ansatz jeweils zur Anwendung kommen sollte.

Ansatz 1: Explizites Laden der Konfiguration

Rufen Sie loadConfiguration() vor start()auf. Dieser Ansatz bietet Ihnen volle Kontrolle über die Konfiguration und ist ideal, wenn Sie benutzerdefinierte Zusammenführungen, umgebungsspezifische Einstellungen oder den Austausch von Vorlagenparametern durchführen möchten. Weitere Informationen zum Einrichten der Konfiguration finden Sie im Abschnitt Erweitern der Initialisierung.

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

// Merge multiple config files into a single configuration object
const combinedConfig = {
  ...appConfig,
  ...featureFlags,
  // Add environment-specific overrides
  API_BASE_URL: process.env.REACT_APP_API_BASE_URL || 'http://localhost:3000',
  FEATURE_NEW_DASHBOARD: process.env.REACT_APP_FEATURE_NEW_DASHBOARD === 'true',
};

// Parameters for template substitution (optional)
const templateParams = {
  environment: process.env.NODE_ENV,
  version: process.env.REACT_APP_VERSION || '1.0.0',
};

// Load configuration with optional template parameters
loadConfiguration(combinedConfig, templateParams);

export const startApp = (): void => {
  start(Jutro, {
    rootId: 'root',
    messageLoader: loadAppMessages,
    coreMessageLoader: loadCoreMessages,
    appName: messages.appName,
    appDescription: messages.appDescription,
    // Config prop is not passed here
  });
};

Ansatz 2: Konfiguration mit der config-Eigenschaft

Übergeben Sie die Konfiguration über die config-Eigenschaft direkt an die start()-Funktion. Die start()-Funktion ruft intern loadConfiguration() auf. Dieser einfachere Ansatz empfiehlt sich bei einer einzelnen Konfigurationsdatei, die keine zusätzliche Verarbeitung erfordert:

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

export const startApp = (): void => {
  start(Jutro, {
    rootId: 'root',
    config: [appConfig], // Configuration loaded by start()
    messageLoader: loadAppMessages,
    // ... other props
  });
};

Keine Vermischung der Konfigurationsansätze

Rufen Sie in derselben startApp-Funktion nicht gleichzeitig loadConfiguration() auf und übergeben die config-Eigenschaft. Dies führt dazu, dass loadConfiguration() zweimal aufgerufen wird. Einmal über den expliziten Aufruf und einmal intern durch start(). Der zweite Aufruf überschreibt den ersten, wodurch möglicherweise wichtige Konfigurationsdaten verloren gehen:

Beispiel dafür, wie eine Konfiguration nicht initialisiert werden sollte:

loadConfiguration(appConfig); // First call
start(Jutro, {
  config: [appConfig], // Triggers second loadConfiguration() call - overwrites the first!
  // ... other props
});

Erweitern der Initialisierung

Über die Grundeinrichtung hinaus können Sie die startApp-Datei um erweiterte Konfigurationen, die Initialisierung von Diensten und benutzerdefinierte Logik ergänzen. In diesem Abschnitt werden gängige Erweiterungsmuster behandelt.

Modulimporte

Neben den grundlegenden Theme- und Stylesheet-Importen können Sie den Abschnitt für Modulimporte um zusätzliche Bibliotheken, Dienstprogramme und Dienste erweitern, die für Ihre Anwendung erforderlich sind. Zu den üblichen Erweiterungen gehören:

• Überwachungs- und Analysebibliotheken: Importieren von Drittanbieterdiensten wie Datadog, Google Analytics oder benutzerdefinierte Tracking-Tools.
• Unterstützung älterer Komponenten: Hinzufügen von Kompatibilitätsebenen für ältere Jutro-Komponenten.
• Routing-Anpassungen: Importieren von Verlaufsdienstprogrammen wie createBrowserHistory für benutzerdefinierte Routerkonfigurationen.
• Anwendungsdienstprogramme: Laden von benutzerdefinierten Dienstprogrammfunktionen, Hilfsprogrammen für die Datentransformation oder anwendungsspezifischen Tools.
• Paketmetadaten: Importieren von package.json für Versionsinformationen, die bei der Überwachung oder beim Debuggen verwendet werden.

Beispiel für erweiterte Modulimporte

import '@jutro/theme';
import './styles/index.scss';
import { start } from '@jutro/app';
import { datadogRum } from '@datadog/browser-rum';
import { configureLegacyComponentMap } from '@jutro/legacy/uiconfig';
import { createBrowserHistory } from 'history';
import packageJson from '../package.json';

Das Hauptprinzip besteht darin, Module in der Reihenfolge zu importieren, in der sie benötigt werden, wobei die Konfigurationsdienstprogramme und die Dienstinitialisierung vor dem Funktionsaufruf von start() erfolgen.

Konfigurationseinrichtung

Sie können nicht nur eine einzelne config.json-Datei laden, sondern auch die Konfigurationseinstellungen für komplexe Anwendungseinstellungen, umgebungsspezifische Werte und die Laufzeitkonfiguration erweitern. Zu den Konfigurationserweiterungsoptionen gehören:

• Mehrere Konfigurationsdateien: Laden verschiedener Konfigurationsdateien für unterschiedliche Belange (Funktionen, API-Endpunkte, UI-Einstellungen).
• Umgebungsspezifische Konfiguration: Laden verschiedener Konfigurationen basierend auf der Bereitstellungsumgebung.
• Laufzeitkonfiguration: Dynamisches Festlegen von Konfigurationswerten auf der Grundlage von Bedingungen oder externen Daten.
• Feature-Flags: Aktivieren/Deaktivieren von Funktionen über die Konfiguration.
• Konfigurationsvalidierung: Validieren der Konfigurationswerte vor dem Start der Anwendung.

Beispiel für eine erweiterte Konfigurationseinrichtung

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

// Merge multiple config files into a single configuration object
const combinedConfig = {
  ...appConfig,
  ...featureFlags,
  // Add environment-specific overrides
  API_BASE_URL: process.env.REACT_APP_API_BASE_URL || 'http://localhost:3000',
  FEATURE_NEW_DASHBOARD: process.env.REACT_APP_FEATURE_NEW_DASHBOARD === 'true',
};

// Parameters for template substitution (optional)
const templateParams = {
  environment: process.env.NODE_ENV,
  version: process.env.REACT_APP_VERSION || '1.0.0',
};

// Load configuration with optional template parameters
loadConfiguration(combinedConfig, templateParams);

Die loadConfiguration()-Funktion unterstützt bis zu drei Argumente: das Hauptkonfigurationsobjekt, optionale Vorlagenparameter für die Variablenersetzung mit der Mustache-Syntax und eine optionale Basiskonfiguration.

Note: Vermeiden Sie die Verwendung des Parameters baseConfig, da er abgekündigt wurde. Es wird empfohlen, Konfigurationen vor dem Aufruf von loadConfiguration() manuell zusammenzuführen, anstatt auf die interne Zusammenführungslogik der Funktion zu vertrauen.

Dienstinitialisierung

Nach der Konfigurationseinrichtung und vor dem Aufruf von start() können Sie externe Dienste, Überwachungstools und anwendungsspezifische Hilfsprogramme initialisieren, die für Ihre Anwendung erforderlich sind. Zu den üblichen Dienstinitialisierungen gehören:

• Überwachung und Analysen: Initialisieren von Tracking-Diensten wie Google Analytics, Datadog RUM oder benutzerdefinierte Überwachungslösungen.
• Unterstützung älterer Komponenten: Konfigurieren von Kompatibilitätsebenen für ältere Jutro-Komponenten mithilfe von configureLegacyComponentMap().
• Umgebungsbasiertes Dienstverhalten: Bedingtes Aktivieren/Deaktivieren von Diensten basierend auf der Umgebung (z. B. Analysen nur in der Produktion, Debugging-Tools nur in der Entwicklung).
• Initialisierung von Drittanbieterdiensten: Einrichten externer Dienste, die eine Laufzeitinitialisierung erfordern, vor dem Start der Anwendung.

Beispiel für eine erweiterte Dienstinitialisierung

import { datadogRum } from '@datadog/browser-rum';
import { configureLegacyComponentMap } from '@jutro/legacy/uiconfig';
import { warning } from '@jutro/logger';
import packageJson from '../package.json';

// Configure legacy component support
configureLegacyComponentMap();

// Environment-specific setup
const deployEnv = process.env.REACT_APP_DEPLOY_ENV || 'development';

// Initialize monitoring (Datadog RUM example)
datadogRum.init({
  applicationId: process.env.REACT_APP_DATADOG_RUM_APPLICATION_ID as string,
  clientToken: process.env.REACT_APP_DATADOG_RUM_CLIENT_TOKEN as string,
  site: 'datadoghq.com',
  service: 'my-jutro-app',
  version: packageJson.version,
  env: deployEnv,
  sessionSampleRate: 100,
  sessionReplaySampleRate: 20,
  trackUserInteractions: true,
  defaultPrivacyLevel: 'mask-user-input',
  trackResources: true,
  trackLongTasks: true,
  // Configure distributed tracing for supported APIs
  allowedTracingUrls: [process.env.REACT_APP_API_BASE_URL].filter(Boolean),
});

// Development-specific warnings
if (process.env.NODE_ENV !== 'production') {
  warning(
    `App running with NODE_ENV=${process.env.NODE_ENV} which may impact performance.`
  );
}

Bewährte Verfahren für die Dienstinitialisierung

• Umgebungsprüfungen: Verwenden Sie Umgebungsvariablen, um Dienste bedingt zu initialisieren (vermeiden Sie die Initialisierung der Nachverfolgung in der Entwicklung).
• Fehlerbehandlung: Umschließen Sie die Dienstinitialisierung in try-catch-Blöcken, um Startfehler zu vermeiden.
• Reihenfolge der Abhängigkeiten: Initialisieren Sie Dienste in der richtigen Reihenfolge basierend auf ihren Abhängigkeiten.
• Konfigurationsvalidierung: Validieren Sie die erforderlichen Umgebungsvariablen, bevor Sie Dienste initialisieren.
• Graceful Degradation: Die Anwendung kann auch dann gestartet werden, wenn nicht kritische Dienste nicht initialisiert werden können.

Internationalisierungseinrichtung

Die Standardinitialisierung ermöglicht eine umfassende Internationalisierungseinrichtung, einschließlich getrenntem Laden von Kern- und Anwendungsnachrichten, Globalisierungsspeicherverwaltung und konfigurationsgesteuerten Gebietsschemaeinstellungen. Dies kann erweitert werden, indem Sie einen Globalisierungsspeicher oder benutzerdefinierte Nachrichten-Loader einrichten:

import { createG11nLocalStorageStore } from '@jutro/locale';

const g11nStore = createG11nLocalStorageStore({
  name: 'my-app-g11n-store',
});

export const startApp = (): void => {
  start(MyApp, {
    rootId: 'root',
    messageLoader: loadAppMessages,
    coreMessageLoader: loadCoreMessages,
    g11nStore, // Enable globalization store
    appName: messages.appName,
    appDescription: messages.appDescription,
  });
};

Weitere Konfigurationsmöglichkeiten finden Sie in der i18n-Dokumentation und unter Interaktion mit dem g11n- Speicher.

Beispiele für erweiterte Konfiguration

Anpassen der Ladekomponente

Verwenden Sie die loaderComponent-Eigenschaft, um den Standard-Loader durch einen benutzerdefinierten Loader zu ersetzen:

import { Loader } from '@jutro/components';

const CustomLoader = ({ loaded, children }) => {
  if (!loaded) {
    return (
      <div style={{ textAlign: 'center', padding: '2rem' }}>
        <h1>Loading Application...</h1>
        <Loader />
      </div>
    );
  }
  return children;
};

start(MyApp, {
  loaderComponent: CustomLoader,
  // ... other configuration
});

Ausführen der Initialisierungslogik vor dem Start

Verwenden Sie den onInit-Rückruf, um Einrichtungscode auszuführen, bevor Ihre Anwendung gerendert wird:

start(MyApp, {
  onInit: () => {
    // Initialize services before app starts
    // This runs synchronously, before DOM rendering
    initializeCustomAnalytics();
    setupLogger();
    validateEnvironmentConfig();
  },
  // ... other configuration
});

Ausführungsreihenfolge:

1. Konfiguration über loadConfiguration() geladen
2. onInit() aufgerufen
3. Validierung von DOM-Elementen und Erstellung eines React-Roots
4. Rendern und Mounten von Komponenten
5. onRender() aufgerufen (falls angegeben)

Best Practices für onInit:

• Verwenden Sie stattdessen onRender, wenn nach dem Rendern Code ausgeführt werden soll.
• Alle ausgelösten Fehler verhindern, dass die Anwendung gestartet wird.
• Verwenden Sie dies für kritische Initialisierungen, die erfolgen müssen, bevor die Benutzeroberfläche gerendert werden kann.

Ausführen von Logik nach dem Rendern

Verwenden Sie den onRender-Rückruf, um Code auszuführen, nachdem die Anwendungskomponente gerendert wurde:

start(MyApp, {
  onRender: () => {
    // This runs after React rendering completes
    // Ideal for non-critical initialization, analytics, or tracking
    logApplicationStartTime();
    initializeOptionalFeatures();
  },
  // ... other configuration
});

Verwendung von onRender:

• Nicht kritische Initialisierung, die den Start nicht behindert
• Analyse oder Telemetrie
• Evaluierung von Feature-Flags
• Optionale Funktionsinitialisierung

Stamm-HOCs (Higher-Order Components, Komponenten höherer Ordnung)

Die an start() übergebene rootHOCs-Eigenschaft ermöglicht es, die Anwendung mit zusätzlichen Kontextanbietern zu umschließen. Sie unterstützt eine Funktion (oder ein Array von Funktionen), die React.ReactNode als Eingabe erhält und eine umschlossene Version zurückgibt.

Note: rootHOCs unterstützt nicht das herkömmliche HOC-Muster, wie es in React definiert ist. Es gilt die Einschränkung, nur ein einziges Argument des Typs React.ReactNode zu unterstützen und keine Komponentenklasse zu verwenden.

Gültige rootHOCs-Muster

// Valid: Takes a ReactNode and returns JSX
const withCustomProvider = (node: React.ReactNode) => {
  return <CustomContext.Provider value={config}>{node}</CustomContext.Provider>;
};

start(MyApp, {
  rootHOCs: [withCustomProvider],
  // ... other configuration
});

Ungültige rootHOCs-Muster

// Invalid: Traditional HOC pattern - wraps components, not nodes
const withDivHOC = (Component: React.ComponentType) => {
  const Wrapper = (props) => (
    <div>
      <Component {...props} />
    </div>
  );
  return Wrapper;
};

// This will not work with rootHOCs
start(MyApp, {
  rootHOCs: [withDivHOC],
});

Allgemeine Konfigurationsmuster

Hinzufügen der Zustandsverwaltung mit Redux

Verwenden Sie die rootHOCs-Eigenschaft, um die Anwendung mit einem Redux-Speicheranbieter zu umschließen:

import { Provider } from 'react-redux';
import { configureStore } from '@reduxjs/toolkit';

const store = configureStore({ reducer: yourReducer }); // Your Redux store configuration

start(RatingApp, {
  messageLoader: loadMessages,
  appName: messages.appName,
  // Wrap application with Redux store
  rootHOCs: [(body) => <Provider store={store}>{body}</Provider>],
  // ... other configuration
});