This library is deprecated and will be archived.
Its functionality has been moved into frontend-platform, which should be used for frontend development going forward. Please contact @edx/fedx-team with any questions.
Foundational application management code for Open edX micro-frontend applications.
frontend-base
provides Open edX micro-frontends with:
- A standardized, yet customizable application initialization process.
- Lifecycle event subscriptions for startup sequence extension.
- Convenient access to environment configuration and application state data.
- A React-based application data provider.
- High-level logging of events and errors to promote observability.
- Fallback error handling.
With respect to the initialization process, frontend-base
helps manage the vast majority of what we expect all Open edX micro-frontends to have by default, namely:
- Environment configuration
- Authentication / access to an authenticated API client
- Analytics
- Logging
- Internationalization
This repo has an example app that demonstrates basic usage of the library.
npm install # do this once
npm start # starts the dev server
Visit http://localhost:8080/ in your browser.
The jest test suite can be run with:
npm test
Initialization is managed via the App
singleton.
The simplest initialization sequence looks like this:
import { App, APP_READY } from '@edx/frontend-base';
import HelloWorld from './HelloWorld'; // Your application component
App.subscribe(APP_READY, () => {
ReactDOM.render(
<HelloWorld />
)
});
App.initialize();
This initialization sequence will do the following:
- Read in expected environment configuration variables and validate that they're not
undefined
- Configure NewRelicLoggingService for @edx/frontend-logging.
- Verify that the user is logged in and authenticated, with a current JWT token.
- Redirect the user to login if they're not authenticated.
- Initialize i18n without any messages.
- Configure analytics with Segment.
If an error occurs during the initialization sequence, the application will go into an error state and log the error to the logging service.
You can hook into this state by subscribing to the APP_ERROR
event. For convenience, frontend-base
provides a simple <ErrorPage>
component that can be used to display errors to the user of the app as a fallback error experience. This experience can be used as-is (shown below), or replaced with your own error page experience.
App.subscribe(APP_ERROR, (error) => {
ReactDOM.render(<ErrorPage />, document.getElementById('root'));
});
It's recommended that in React applications you use error boundaries to catch run-time errors in your React components.
frontend-base
provides an error boundary component which displays <ErrorPage>
in the event of an uncaught error in React. If you use <AppProvider>
then you'll get this behavior for free.
If you need a custom error page, you can add your own error boundary inside <AppProvider>
and the fallback handling will effectively be ignored (since errors won't bubble up to it anymore).
frontend-base
also provides several companion React components which pair with the App singleton to help bootstrap your React application. Please see the API documentation for <AppProvider>
and <AppContext>
specifically; they're an important part of the frontend-base ecosystem.