概览

见 完整文档的 GitHub 页面网站。 。 。 .

前端-平面是Open edX微前端应用程序及其辅助库的适度应用框架. 它提供几种基础服务,所有Open edX微前端都应该有:

此外,前端平台还提供可扩展的应用程序初始化生命周期来帮助管理上述服务的配置,使应用程序开发人员能够专注于地物开发.

开始

未升级节点/ npm 的一次性设置

安装 nvm

这被强烈地推荐为能够利用不同的节点/npm版本. 一段时间以来,不同的寄存器可能使用不同的节点/npm版本.

切换到此 repo 的节点/ npm 版本

在项目的根目录中, 运行 nvm use 将环境设置为正确的节点版本。 如果没有安装所需的节点或npm版本,nvm将提示您安装.

清理出旧节点模块并重新安装

需要这个步骤是因为节点现在使用不同的包锁格式,必须重新安装 基于此新软件包文件的依赖性 。 删除 node_modules运行 npm ci。 。 。 .

标准开始步骤

1. npm install
2. npm start
3. 打开 http://local.openedx.io:8080 查看示例应用.

建筑

上述四个基础服务(分析、认证、i18n和伐木)是通过前端平台的API层,作为对应用程序的进口。 初始化序列创建了每个服务的一例并暴露出其作为功能输出的方法,在服务实施与应用代码中的使用之间形成了一层抽象.

每类服务都有一份记录的API合同,服务执行必须履行。 这样可以在必要时使用不同的服务实施,而无需更新以消耗应用程序.

服务架构

内部,服务实施与其余平台严格隔离. 他们的阶级以他们的依附关系作为其建构者的论据. 这意味着,例如,如果分析依赖于伐木,则需要参考符合以下条件的实例: LoggingService 界面作为当它被即时化时的选项。 它不能直接从日志模块导入 。 换句话说,默认的服务实施可能为了方便而与服务接口合用同一位置,但他们理论上可以住在自己的寄存器中,这不需要任何重构.

同样地,平台代码也不应该使用由于同样原因不属于有文件记载的界面的服务方法.

应用程序初始化

前端平台提供了一个 initialize() 函数,用于设置和配置应用程序。 这个 initialize() 函数使用一组 合理默认 除非另有说明,否则用反映Open edX在分析、认证、国际化和伐木方面最佳做法的服务来拖住应用程序.

初始化过程分出一系列阶段进行,为初始化的应用代码提供了连接到进程并按所希望的自定义设置的机会:

• 初始化前
• Pub/Sub 已初始化
• 已装入环境配置文档
• 日志服务已初始化
• 认证服务已初始化
• 分析服务初始化
• 国际化服务初始化
• 应用程序已就绪

大多数的应用不需要做任何特殊的事情.

应用程序配置

当应用程序加载时,会从中加载已知环境变量列表 process.env 进入它通过它暴露的物体 getConfig - 这里的要点主要是 把我们的代码 与使用 process.env 这也许并不总是我们选择配置应用程序的方式。 应用程序初始化生命周期支持运行时间配置,同时通过 config 处理器,记录在 初始化函数。如果想要将一个变量输入它不期望的配置,您可以使用 mergeConfig 初始化时从 process.env。 。 。 .

这样的例子可能是这样的:

initialize({
  // ... other initialization options
  handlers: {
    config: () => {
      mergeConfig({
        CUSTOM_VARIABLE: process.env.CUSTOM_VARIABLE || null,
      }, 'Custom app config');
    },
  },
});

当通过运行时配置 mergeConfig 如上所述, getConfig 要返回配置对象中添加的密钥和值,必须在组件的渲染寿命周期内调用。 若为 getConfig 被调用到组件渲染寿命周期之外,自定义配置密钥/值对最初将不会是返回对象的一部分 getConfig。例如:

import { getConfig } from '@edx/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.
console.log(getConfig().CUSTOM_VARIABLE); // returns undefined

const ExampleComponent = () => {
  // This returns the value as expected since it is called after `mergeConfig` has already been executed.
  console.log(getConfig().CUSTOM_VARIABLE)
};

覆盖默认外部链接

A 类 getExternalLinkUrl 函数在 config.js 用于覆盖默认的外部链接。 要使用此功能,请提供一个将默认链接映射到自定义链接的对象. 此对象应添加到 config 定义对象 env.config.[js,jsx,ts,tsx]名称 externalLinkUrlOverrides。这里有一个例子:

// env.config.js

const config = {
  // other custom configuration here
  externalLinkUrlOverrides: {
    "https://docs.openedx.org/en/latest/educators/index.html": "https://custom.example.com/educators/index.html",
    "https://creativecommons.org/licenses": "https://www.tldrlegal.com/license/creative-commons-attribution-cc",
  },
};

export default config;

服务接口

前端平台提供的每项服务(分析、认证、i18n、伐木)都有一个API合同,该合同的所有实施都得到保证。 使用前端平台的应用程序可以通过一套方便的导出功能使用其配置的服务. 一个想要使用服务接口的应用程序只需要通过初始化()函数来初始化它们,可以选择地提供所希望的自定义服务接口(你可能不需要).

服务实施

此寄存器包含默认服务执行以方便. 这些实施与消费服务接口合用同一地点,以方便开发,但两者应保持不变 严格 模块化和分离.

包括的服务实施包括:

• 新遗迹 (博客)
• 部分(分析)
• Axios/JWT(秋季)
• 反应入(i18n)

注:截至本文,i18n为 没有 相会相会. 这个 initialize() 函数不允许应用程序提供替代的 i18n 执行;这是因为 i18n 的接口和执行尚未分离和模块化.

本地开发和测试

在修改前端平台时, 请确保手动运行位于其中的包含实例应用程序 ./example。示例应用包括两个路径,用于测试未经认证和认证的用户。 要启动示例应用程序, 请运行 npm start 从根目录.

如果您要测试本地微前端对前端平台的修改, 请遵循这里的方向 : https://github.com/openedx/frontend-building# 本地-模块-配置-为网络包装

获得示例应用程序与导师 Dev 环境合作

部分的示例应用功能包括API请求在用户的配置信息中得到登录. 由于CORS的限制,此请求默认会失败. 为了克服这个,补丁 openedx-lms-development-settings 以下设置( 通过一个导师插件) :

# Used for the example app in the frontend-plugin library
CORS_ORIGIN_WHITELIST.append("http://local.openedx.io:8080")
LOGIN_REDIRECT_WHITELIST.append("local.openedx.io:8080")
CSRF_TRUSTED_ORIGINS.append("http://local.openedx.io:8080")

确保插件安装、启用并运行 tutor dev restart lms 以确保新配置被取出.

生产部署战略

对于前端站台上所搭建的任何MFE,部署策略将大致如下:

1. 在命令行上运行带有环境变量的构建脚本,以便在任何相关的配置中通过. 示例

   NODE_ENV=development BASE_URL=open.edx.org ETC=etc npm run build
   

   这将创建一个包含可部署文物的Dist/目录.

2. 复制 dist/ 的内容到网络服务器 .

3. 配置用于指向您的 MFE 的平台 。 (详情关于这个即将到来)