Skip to content

Commit

Permalink
docs: change @edx for @openedx in the package management and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcoa
dcoa committed May 23, 2024
1 parent 9814fb3 commit 94e4a62
Show file tree
Hide file tree
Showing 4 changed files with 1,384 additions and 2,038 deletions.
18 changes: 9 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
[![Build Status](https://github.com/openedx/frontend-platform/actions/workflows/ci.yml/badge.svg)](https://github.com/openedx/frontend-platform/actions/workflows/ci.yml)
[![Codecov](https://img.shields.io/codecov/c/github/edx/frontend-platform)](https://codecov.io/gh/edx/frontend-platform)
[![NPM Version](https://img.shields.io/npm/v/@edx/frontend-platform.svg)](https://www.npmjs.com/package/@edx/frontend-platform)
[![npm_downloads](https://img.shields.io/npm/dt/@edx/frontend-platform.svg)](https://www.npmjs.com/package/@edx/frontend-platform)
[![license](https://img.shields.io/npm/l/@edx/frontend-platform.svg)](https://github.com/openedx/frontend-platform/blob/master/LICENSE)
[![NPM Version](https://img.shields.io/npm/v/@openedx/frontend-platform.svg)](https://www.npmjs.com/package/@openedx/frontend-platform)
[![npm_downloads](https://img.shields.io/npm/dt/@openedx/frontend-platform.svg)](https://www.npmjs.com/package/@opeedx/frontend-platform)
[![license](https://img.shields.io/npm/l/@openedx/frontend-platform.svg)](https://github.com/openedx/frontend-platform/blob/master/LICENSE)
[![semantic release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

# Overview
Expand All @@ -13,11 +13,11 @@ frontend-platform is a modest application framework for Open edX micro-frontend

| Service | Module location |
|------------------------------------|----------------------------------|
| Analytics | @edx/frontend-platform/analytics |
| Logging | @edx/frontend-platform/logging |
| Authenticated API client (auth) | @edx/frontend-platform/auth |
| Internationalization (i18n) | @edx/frontend-platform/i18n |
| Misc (init, config, pubSub, utils) | @edx/frontend-platform |
| Analytics | @openedx/frontend-platform/analytics |
| Logging | @openedx/frontend-platform/logging |
| Authenticated API client (auth) | @openedx/frontend-platform/auth |
| Internationalization (i18n) | @openedx/frontend-platform/i18n |
| Misc (init, config, pubSub, utils) | @openedx/frontend-platform |

-------------------------------------------------------------------------

Expand Down Expand Up @@ -101,7 +101,7 @@ initialize({
When using runtime configuration via `mergeConfig` noted above, `getConfig` must be called within a component's render lifecycle for the added keys and values to be returned in the configuration object. If `getConfig` is called outside of a component's render lifecycle, the custom configuration key/value pairs will not initially be part of the object returned by `getConfig`. For example:

```jsx
import { getConfig } from '@edx/frontend-platform/config';
import { getConfig } from '@openedx/frontend-platform/config';

// The runtime configuration `CUSTOM_VARIABLE` added in the above code snippet will not appear here. This is
// because `getConfig` is called before `mergeConfig` is executed to add the custom runtime configuration.
Expand Down
12 changes: 6 additions & 6 deletions docs/how_tos/theming.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## Overview

This document serves as a guide to using `@edx/frontend-platform` to support MFE theming with Paragon using theme CSS loaded externally (e.g., from a CDN).
This document serves as a guide to using `@openedx/frontend-platform` to support MFE theming with Paragon using theme CSS loaded externally (e.g., from a CDN).

To do this, configured URLs pointing to relevant CSS files from `@openedx/paragon` and (optionally) `@openedx/brand-openedx` are loaded and injected to the HTML document at runtime. This differs than the consuming application importing the styles from `@openedx/paragon` and `@openedx/brand-openedx` directly, which includes these styles in the application's production assets.

By serving CSS loaded externally, consuming applications of Paragon no longer need to be responsible for compiling the theme SCSS to CSS themselves and instead use a pre-compiled CSS file. In doing so, this allows making changes to the Paragon theme without needing to necessarily re-build and re-deploy all consuming applications.

### Dark mode and theme variant preferences

`@edx/frontend-platform` supports both `light` (required) and `dark` (optional) theme variants. The choice of which theme variant should be applied on page load is based on the following preference cascade:
`@openedx/frontend-platform` supports both `light` (required) and `dark` (optional) theme variants. The choice of which theme variant should be applied on page load is based on the following preference cascade:

1. **Get theme preference from localStorage.** Supports persisting and loading the user's preference for their selected theme variant, until cleared.
1. **Detect user system settings.** Rely on the `prefers-color-scheme` media query to detect if the user's system indicates a preference for dark mode. If so, use the default dark theme variant, if one is configured.
Expand All @@ -26,7 +26,7 @@ If your use case necessitates additional variants beyond the default supported `

There is also a meaningful improvement in performance as loading the compiled theme CSS from an external CDN means micro-frontends (MFEs) can include cached styles instead of needing to load essentially duplicate theme styles included in each individual MFE as users navigate across the platform.

However, as the styles from `@openedx/paragon` and `@openedx/brand-openedx` get loaded at runtime by `@edx/frontend-platform`, the associated CSS files do not get processed through the consuming application's Webpack build process (e.g., if the MFE used PurgeCSS or any custom PostCSS plugins specifically for Paragon).
However, as the styles from `@openedx/paragon` and `@openedx/brand-openedx` get loaded at runtime by `@openedx/frontend-platform`, the associated CSS files do not get processed through the consuming application's Webpack build process (e.g., if the MFE used PurgeCSS or any custom PostCSS plugins specifically for Paragon).

### Falling back to styles installed in consuming application

Expand Down Expand Up @@ -118,7 +118,7 @@ export default config;

### MFE runtime configuration API

`@edx/frontend-platform` additionally supports loading application configuration from the MFE runtime configuration API via `edx-platform`. The configuration is served by the `http://localhost:18000/api/mfe_config/v1` API endpoint. For more information, refer to [this documentation](https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst) about the MFE runtime configuration API, please see these docs.
`@openedx/frontend-platform` additionally supports loading application configuration from the MFE runtime configuration API via `edx-platform`. The configuration is served by the `http://localhost:18000/api/mfe_config/v1` API endpoint. For more information, refer to [this documentation](https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst) about the MFE runtime configuration API, please see these docs.

The application configuration may be setup via Django settings as follows:

Expand Down Expand Up @@ -154,7 +154,7 @@ https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css
```

In the event the other Paragon CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN url throws a 404), `@edx/frontend-platform` will attempt to fallback to injecting the locally installed Paragon CSS from the consuming application into the HTML document.
In the event the other Paragon CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN url throws a 404), `@openedx/frontend-platform` will attempt to fallback to injecting the locally installed Paragon CSS from the consuming application into the HTML document.

## Usage with `@openedx/brand-openedx`

Expand Down Expand Up @@ -201,4 +201,4 @@ https://cdn.jsdelivr.net/npm/@openedx/brand-openedx@$brandVersion/dist/core.min.
https://cdn.jsdelivr.net/npm/@openedx/brand-openedx@$brandVersion/dist/light.min.css
```

In the event the other brand override CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN is down), `@edx/frontend-platform` will attempt to fallback to injecting the locally installed brand override CSS urls from the consuming application into the HTML document.
In the event the other brand override CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN is down), `@openedx/frontend-platform` will attempt to fallback to injecting the locally installed brand override CSS urls from the consuming application into the HTML document.
Loading

0 comments on commit 94e4a62

Please sign in to comment.