+ );
+}
+
+export default React.memo(function App() {
+ return (
+
+
+
+ );
+});
diff --git a/__fixtures__/remote-view/packages/view1/src/__tests__/index.test.tsx b/__fixtures__/remote-view/packages/view1/src/__tests__/index.test.tsx
new file mode 100644
index 000000000..74a06d6e5
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view1/src/__tests__/index.test.tsx
@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { render } from 'react-dom';
+import View1 from '../index';
+
+test('it should render', () => {
+ const el = document.createElement('div');
+ expect(() => render(, el)).not.toThrow();
+});
diff --git a/__fixtures__/remote-view/packages/view1/src/index.css b/__fixtures__/remote-view/packages/view1/src/index.css
new file mode 100644
index 000000000..88d154715
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view1/src/index.css
@@ -0,0 +1,16 @@
+.card-component {
+ width: 480px;
+ margin: auto;
+}
+
+.card-component .card {
+ background-color: #f9f9f9;
+}
+
+.card-component .group {
+ margin-bottom: 5px;
+}
+
+.card-component .button {
+ margin-top: 14px;
+}
diff --git a/__fixtures__/remote-view/packages/view1/src/index.tsx b/__fixtures__/remote-view/packages/view1/src/index.tsx
new file mode 100644
index 000000000..0d7b8fb41
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view1/src/index.tsx
@@ -0,0 +1,6 @@
+import * as React from 'react';
+import App from './App';
+
+export default function View1(): JSX.Element {
+ return ;
+}
diff --git a/__fixtures__/remote-view/packages/view2/README.md b/__fixtures__/remote-view/packages/view2/README.md
new file mode 100644
index 000000000..e48565e74
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view2/README.md
@@ -0,0 +1 @@
+This is a component
diff --git a/__fixtures__/remote-view/packages/view2/package.json b/__fixtures__/remote-view/packages/view2/package.json
new file mode 100644
index 000000000..7f1f9a6f3
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view2/package.json
@@ -0,0 +1,16 @@
+{
+ "name": "view2",
+ "version": "1.0.0",
+ "main": "src/index.tsx",
+ "license": "UNLICENSED",
+ "modular": {
+ "type": "esm-view",
+ "externalCdnTemplate": "https://esm.sh/[name]@[version]"
+ },
+ "dependencies": {
+ "react": "18.2.0",
+ "react-dom": "18.2.0",
+ "minifaker": "1.34.1",
+ "regular-table": "0.5.6"
+ }
+}
diff --git a/__fixtures__/remote-view/packages/view2/src/App.tsx b/__fixtures__/remote-view/packages/view2/src/App.tsx
new file mode 100644
index 000000000..eb33dd2fb
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view2/src/App.tsx
@@ -0,0 +1,124 @@
+import 'regular-table/dist/css/material.css';
+import React, { useEffect, useRef } from 'react';
+import 'regular-table';
+import type {
+ RegularTableElement,
+ DataResponse,
+ MetaData,
+} from 'regular-table';
+/* @ts-expect-error */
+import { default as en } from 'minifaker/locales/en';
+import { default as minifaker, country, domainName, word } from 'minifaker';
+
+minifaker.addLocale('en', en);
+
+interface ExtendedResponse extends DataResponse {
+ metadata: string[][];
+}
+
+interface ExtendedMetadata extends MetaData {
+ user: 'green' | 'red';
+}
+
+const colors = { green: '#e4ebe4', red: '#f1dbdb' };
+
+function createPeople(n: number) {
+ const map = [
+ () =>
+ `${capitalize(word({ type: 'adjective' }))} ${capitalize(
+ word({ type: 'noun' }),
+ )}`,
+ () => String(Math.ceil(Math.random() * 100)),
+ () => country({ useCode: 'alpha3' }),
+ domainName,
+ () => String((Math.random() * 1000).toFixed(2)),
+ ];
+
+ const columns: string[][] = [];
+ for (let columnIndex = 0; columnIndex < map.length; columnIndex += 1) {
+ const row: string[] = [];
+ for (let rowIndex = 0; rowIndex < n; rowIndex += 1) {
+ row.push(map[columnIndex]());
+ }
+ columns.push(row);
+ }
+ return columns;
+}
+
+function App(): JSX.Element {
+ const view = useRef(null);
+ const regTableInstance = useRef(null);
+
+ const people: string[][] = createPeople(5000);
+
+ useEffect(() => {
+ if (document.getElementById('view2-table')) {
+ console.warn(
+ 'view2 was remounted and attempted to create a new table, cancelling',
+ );
+ return;
+ }
+ const regularTable = document.createElement('regular-table');
+ regularTable.setAttribute('id', 'view2-table');
+ regTableInstance.current = regularTable;
+ view.current?.appendChild(regularTable);
+ function getDataSlice(x0: number, y0: number, x1: number, y1: number) {
+ const metadata = [];
+ for (let i = 0; i < people[4].length; i += 1) {
+ const priceInc = Math.random() * 100 - 50;
+ people[4][i] = String((parseFloat(people[4][i]) + priceInc).toFixed(2));
+ metadata[i] = priceInc < 0 ? 'red' : 'green';
+ }
+
+ const res: ExtendedResponse = {
+ num_rows: people[0].length,
+ num_columns: people.length,
+ data: people.slice(x0, x1).map((col) => col.slice(y0, y1)),
+ column_headers: [
+ ['Company Name'],
+ ['Employees'],
+ ['Country'],
+ ['Domain'],
+ ['Price'],
+ ],
+ metadata: [[], [], [], [], metadata],
+ };
+ return Promise.resolve(res);
+ }
+ const table = regTableInstance.current as RegularTableElement;
+ table.setDataListener(getDataSlice);
+ table.addStyleListener(() => {
+ const ths: NodeListOf =
+ table.querySelectorAll('thead th');
+ for (const th of ths) {
+ th.style.textAlign = 'left';
+ th.style.fontWeight = '900';
+ th.style.padding = '0 0 12px 0';
+ }
+ const thd: NodeListOf =
+ table.querySelectorAll('body td');
+ for (const td of thd) {
+ const meta = table.getMeta(td) as ExtendedMetadata;
+ if (meta.user) {
+ td.style.backgroundColor = colors[meta.user];
+ }
+ }
+ });
+ });
+
+ useEffect(() => {
+ (regTableInstance.current as RegularTableElement).draw();
+ setInterval(
+ () => (regTableInstance.current as RegularTableElement).draw(),
+ 1000,
+ );
+ });
+
+ return ;
+}
+
+function capitalize(s: string) {
+ return s[0].toUpperCase() + s.slice(1);
+}
+
+export default React.memo(App);
diff --git a/__fixtures__/remote-view/packages/view2/src/__tests__/index.test.tsx b/__fixtures__/remote-view/packages/view2/src/__tests__/index.test.tsx
new file mode 100644
index 000000000..af118b981
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view2/src/__tests__/index.test.tsx
@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { render } from 'react-dom';
+import View2 from '../index';
+
+test('it should render', () => {
+ const el = document.createElement('div');
+ expect(() => render(, el)).not.toThrow();
+});
diff --git a/__fixtures__/remote-view/packages/view2/src/index.tsx b/__fixtures__/remote-view/packages/view2/src/index.tsx
new file mode 100644
index 000000000..0d7b8fb41
--- /dev/null
+++ b/__fixtures__/remote-view/packages/view2/src/index.tsx
@@ -0,0 +1,6 @@
+import * as React from 'react';
+import App from './App';
+
+export default function View1(): JSX.Element {
+ return ;
+}
diff --git a/docs/components/index.md b/docs/components/index.md
new file mode 100644
index 000000000..5f48feea7
--- /dev/null
+++ b/docs/components/index.md
@@ -0,0 +1,9 @@
+---
+has_children: true
+title: Components
+nav_order: 2
+---
+
+# Components
+
+Components that are designed to work with Modular.
diff --git a/docs/components/remote-view.md b/docs/components/remote-view.md
new file mode 100644
index 000000000..2f51b132f
--- /dev/null
+++ b/docs/components/remote-view.md
@@ -0,0 +1,332 @@
+---
+parent: Components
+title:
+---
+
+# ``
+
+`` is a Modular React component that enables the micro-frontend
+pattern using Modular [ESM views](https://modular.js.org/esm-views/).
+
+## Features
+
+- Build distributed UIs using the microfrontend pattern, thanks to Modular
+ [ESM Views](https://modular.js.org/esm-views/) and an
+ [ESM CDN](https://modular.js.org/esm-views/esm-cdn/)
+- Supports loading local and global CSS
+- Flexible error handling
+- Declaratively fall back to iframes
+- Compatible with any ESM CDN
+- Also supports Modular [apps](https://modular.js.org/package-types/) via
+ iframes
+
+## Prerequisites
+
+To natively load ESM Views via ``, it is required that:
+
+1. The host (or "portal") application is a Modular
+ [ESM View](https://modular.js.org/esm-views/) itself
+2. The version of React matches between the host and each ESM View being loaded
+
+This is due to the fact that React is a stateful dependency and loading
+[more than 1 copy is unsupported](https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react).
+
+Using an iframe fallback avoids this limitation and may be suitable depending on
+your use-case.
+
+## Getting Started
+
+Install the RemoteView package:
+
+```bash
+yarn add @modular-scripts/remote-view
+```
+
+or
+
+```bash
+npm install @modular-scripts/remote-view
+```
+
+Modular ``s work by
+[dynamically importing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
+your Modular [ESM Views](https://modular.js.org/esm-views) and natively
+rendering them into your React tree.
+
+To achieve this, `` loads
+[ESM View manifests](https://modular.js.org/esm-views/output-package-manifest/)
+that are statically served from a CDN. Once a manifest is fetched,
+`` dynamically imports the ESM View's JS and CSS entrypoints and
+renders them as part of the caller's React tree.
+
+This approach enables the microfrontend pattern, which can also be thought as
+distributed UIs.
+
+`` also supports rendering non-ESM View modules by falling back to
+iframes. In this case, an iframe is rendered in the React tree, instead of a
+native React subtree.
+
+## Example
+
+Load (dynamically import) and render a set of
+[esm-cdn-hosted](https://modular.js.org/esm-views/esm-cdn/) views:
+
+```jsx
+import React, { useState } from 'react';
+import {
+ RemoteViewProvider,
+ RemoteView,
+ RemoteViewErrorBoundary,
+} from '@modular-scripts/remote-view';
+
+function MyPortal() {
+ // In practice, URLs to your remote ESM views can be fetched from a server
+ const [remoteViews, addRemoteView] = useState([
+ 'https://cdn.example.com/esm-view-1',
+ 'https://cdn.example.com/esm-view-2',
+ ]);
+
+ return (
+
+ {remoteViews.map((url, key) => (
+
+
+
+
+
+ ))}
+
+ );
+}
+```
+
+Modular [ESM Views](https://modular.js.org/esm-views) are dynamically loaded,
+whereas Modular [Apps](https://modular.js.org/package-types/app/) are loaded
+into an iframe. For more information on Modular types, check out the
+[Package Types breakdown on the Modular docs](https://modular.js.org/package-types/).
+
+## Fall back to iframes
+
+It is also possible to load [ESM Views](https://modular.js.org/esm-views) (in
+addition to [Apps](https://modular.js.org/package-types/app/)) into an iframe if
+desired - provide `loadWithIframeFallback` prop to trigger the iframe fallback:
+
+```jsx
+// Use an iframe fallback for one particular view
+function determineFallbackCases(manifest: MicrofrontendManifest) {
+ if (manifest.name === '@myscope/example-module') {
+ return true;
+ }
+
+ return false;
+}
+
+return (
+
+ {remoteViews.map((url, key) => (
+
+
+
+
+
+ ))}
+
+);
+```
+
+## Custom loader
+
+You can customize the loading state of each `` by providing a
+`loading` prop:
+
+```jsx
+return (
+
+
+ My custom loading component}
+ />
+
+
+);
+```
+
+By default, `` outputs a very simple loading message:
+`
Loading
`.
+
+Alternatively, you bring your own error boundary.
+
+## Security
+
+Loading dynamic (especially remote, over http(s)) ES modules at runtime carries
+certain risks and must be used carefully. Content loaded dynamically should only
+ever be done from a trusted source.
+
+End user input should **not** be used to determine content URLs (etc) and any
+application of consuming modules at runtime should be centrally controled in a
+secure environment. In other words, user input should not be allowed to modify
+URLs that `` will attempt to render.
+
+There is also no guarantee of safety, which is why it is very strongly
+recommended to use error boundaries. `` attempts to render
+whatever module it finds into your React tree, and this depends on runtime
+imports actually returning valid React modules.
+
+## CSS
+
+`` automatically imports local and global CSS from ESM Views that
+have been specified according to the
+[Modular docs](https://modular.js.org/esm-views/external-css-imports/).
+
+When an iframe fallback is used, this does not apply.
+
+## Error handling
+
+It is strongly recommended to wrap any usage of `` with error
+boundaries. There are two approaches you can take:
+
+- Use the provided ``, optionally customizing the
+ content that is displayed
+- Use your own error boundary
+
+### Using the default error boundary
+
+Outputs a default, simple error component displaying the error details
+
+```jsx
+return (
+
+
+
+
+
+);
+```
+
+The error fallback contains a simple output:
+
+```jsx
+return (
+
+
+ Something went wrong for module at URL
+ "https://cdn.example.com/views/foo".
+
+
{error.message}
+
+);
+```
+
+### Customizing the content of ``
+
+Supply the `content` prop. If the `error` prop is an instance of
+`RemoteViewError`, will contain RemoteView-specific error details.
+
+```tsx
+function MyErrorContent({ error }: { error: Error | RemoteViewError }) {
+ const isRemoteViewError = error instanceof RemoteViewError;
+
+ return (
+
+
A custom error fallback component
+
+ You can render and do anything you want, it's just a React component.
+
+
+ This error:
+
+ Name: {error.name}
+
+
+ Message: {error.message}
+
+ {isRemoteViewError && (
+ RemoteView could not load "{error.remoteViewUrl}"
+ )}
+
+ );
+}
+
+return (
+
+
+
+
+
+);
+```
+
+### Using a fully custom error boundary
+
+The RemoteView subtree can throw a `RemoteViewError` or other `Error` subclass.
+
+If the error relates to the loading of the ESM View, a `RemoteViewError` should
+be thrown. In all other cases (e.g. any crash in the React subtree after
+rendering), an `Error` (of any subclass) will throw.
+
+Use the standard class component `componentDidCatch` API to handle errors as you
+choose.
+
+```jsx
+return (
+
+
+
+
+
+);
+```
+
+Examples of how errors can be handled, including recovery, can be seen in
+[`packages/remote-view-demos`](https://github.com/jpmorganchase/modular/tree/main/packages/remote-view-demos).
+
+## Examples
+
+There are a range of examples implemented in
+[`packages/remote-view-demos`](https://github.com/jpmorganchase/modular/tree/main/packages/remote-view-demos):
+
+- 2 ESM Views loaded and rendering (aka "happy path")
+- Iframe fallback
+- All types of error handling
+- How to recover a crashed view
+
+## API
+
+### ``
+
+Required provider that must wrap any `` instances. Is responsible
+for fetching ESM views.
+
+| Prop | Type | Required? | Description | Default |
+| ------------------------ | --------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------- | ----------- |
+| `urls` | String[] (URLs) | Yes | URLs of the ESM Views you want to load | N/A |
+| `loadWithIframeFallback` | Function `fn(manifest: MicrofrontendManifest) => boolean` | No | Optional function to determine if an iframe fallback should be used in place of a React component. | `undefined` |
+
+### ``
+
+| Prop | Type | Required? | Description | Default |
+| --------- | ------------ | --------- | --------------------------------------------------------------------------------------- | -------------------- |
+| `url` | String (URL) | Yes | URL to the remote view. Can be either an ESM view URL on your ESM CDN, or an iframe URL | N/A |
+| `loading` | JSX.Element | No | Display a custom loading component whilst the remote view is being fetched and rendered | `
Loading
` |
+
+`MicrofrontendManifest` represents the `package.json` of an ESM View served over
+an ESM CDN. This includes fields like the package `name`, `style`,
+`styleImports` and more - see `packages/modular-types/src/types.ts` for the full
+list of fields that are expected. You can also refer to the
+[Modular docs on CSS imports](https://modular.js.org/esm-views/external-css-imports/).
+
+### ``
+
+Recommended (but optional) error boundary component to protect against runtime
+crashes. ``s can throw during attempts to load ESM views
+(unsupported manifests, unreachable manifests), but also inside the subtree that
+is ultimately rendered, which is outside the control of ``.
+
+| Prop | Type | Required? | Description | Default |
+| --------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `content` | React.ComponentType | No | Optional component to customize the error boundary. If provided, receives an `error` prop of type `RemoteViewError` or `Error`. | A simple div that outputs "Something went wrong" with an accompanying error message. |
diff --git a/docs/index.md b/docs/index.md
index 8a765699f..9a832bf78 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -57,6 +57,10 @@ It supports three flags:
- [workspace](./commands/workspace.md)
- [check](./commands/check.md)
+## Components
+
+- [``](./components/remote-view.md)
+
## Concepts
- [Micro-frontends](./concepts/microfrontends.md)
diff --git a/docs/package-types/esm-view.md b/docs/package-types/esm-view.md
index 973eae3f6..e5b42f040 100644
--- a/docs/package-types/esm-view.md
+++ b/docs/package-types/esm-view.md
@@ -159,3 +159,10 @@ ESM Views are generated by `modular add` using the
For an in-depth reference of how ESM Views work and can be customized, see this
[section](../esm-views).
+
+## Usage with ``
+
+The [`` component](../components/remote-view.md) is designed for
+consuming ESM Views in a portal-like application. It aims to make implementing
+the micro-frontend pattern easier. View the
+[`` docs](../components/remote-view.md) for more information.
diff --git a/package.json b/package.json
index 6a322978b..ee0280cd6 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,7 @@
"create-modular-react-app": "ts-node packages/create-modular-react-app/src/cli.ts",
"modular": "ts-node packages/modular-scripts/src/cli.ts",
"test": "yarn modular test --watchAll false --runInBand --env node",
- "build": "yarn workspace @modular-scripts/workspace-resolver build && yarn workspace create-modular-react-app build && yarn workspace modular-scripts build && yarn workspace modular-views.macro build",
+ "build": "yarn workspace @modular-scripts/workspace-resolver build && yarn workspace create-modular-react-app build && yarn workspace modular-scripts build && yarn workspace modular-views.macro build && yarn modular build @modular-scripts/remote-view",
"prepare": "is-ci || husky install",
"postinstall": "patch-package",
"typecheck": "yarn modular typecheck",
diff --git a/packages/modular-scripts/react-scripts/config/utils/esmUtils.js b/packages/modular-scripts/react-scripts/config/utils/esmUtils.js
index b5a1f1922..b6b2dfb33 100644
--- a/packages/modular-scripts/react-scripts/config/utils/esmUtils.js
+++ b/packages/modular-scripts/react-scripts/config/utils/esmUtils.js
@@ -8,7 +8,7 @@ function parsePackageName(name) {
if (!parsedName) {
return;
}
- const [_, scope, module, submodule] = parsedName;
+ const [, scope, module, submodule] = parsedName;
const dependencyName = (scope ? `${scope}/` : '') + module;
return { dependencyName, scope, module, submodule };
}
diff --git a/packages/modular-scripts/src/__tests__/utils/__snapshots__/getWorkspaceInfo.test.ts.snap b/packages/modular-scripts/src/__tests__/utils/__snapshots__/getWorkspaceInfo.test.ts.snap
index 5f410009b..34667ab4e 100644
--- a/packages/modular-scripts/src/__tests__/utils/__snapshots__/getWorkspaceInfo.test.ts.snap
+++ b/packages/modular-scripts/src/__tests__/utils/__snapshots__/getWorkspaceInfo.test.ts.snap
@@ -2,148 +2,134 @@
exports[`getWorkspaceInfo 1`] = `
{
- "location": "packages/modular-types",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 2`] = `
-{
- "location": "packages/workspace-resolver",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [
- "@modular-scripts/modular-types",
- ],
-}
-`;
-
-exports[`getWorkspaceInfo 3`] = `
-{
- "location": "packages/create-modular-react-app",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 4`] = `
-{
- "location": "packages/eslint-config-modular-app",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 5`] = `
-{
- "location": "packages/modular-scripts",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [
- "@modular-scripts/modular-types",
- "@modular-scripts/workspace-resolver",
- ],
-}
-`;
-
-exports[`getWorkspaceInfo 6`] = `
-{
- "location": "packages/modular-template-app",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "template",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 7`] = `
-{
- "location": "packages/modular-template-esm-view",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "template",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 8`] = `
-{
- "location": "packages/modular-template-node-env-app",
- "mismatchedWorkspaceDependencies": [],
- "public": false,
- "type": "template",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 9`] = `
-{
- "location": "packages/modular-template-package",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "template",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 10`] = `
-{
- "location": "packages/modular-template-source",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "template",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 11`] = `
-{
- "location": "packages/modular-template-view",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "template",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 12`] = `
-{
- "location": "packages/modular-views.macro",
- "mismatchedWorkspaceDependencies": [],
- "public": true,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [],
-}
-`;
-
-exports[`getWorkspaceInfo 13`] = `
-{
- "location": "packages/tree-view-for-tests",
- "mismatchedWorkspaceDependencies": [],
- "public": false,
- "type": "unknown",
- "version": Any,
- "workspaceDependencies": [],
+ "@modular-scripts/modular-types": {
+ "location": "packages/modular-types",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "unknown",
+ "version": "1.1.0",
+ "workspaceDependencies": [],
+ },
+ "@modular-scripts/remote-view": {
+ "location": "packages/remote-view",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "package",
+ "version": "0.0.0",
+ "workspaceDependencies": [
+ "@modular-scripts/modular-types",
+ ],
+ },
+ "@modular-scripts/workspace-resolver": {
+ "location": "packages/workspace-resolver",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "unknown",
+ "version": "1.2.0",
+ "workspaceDependencies": [
+ "@modular-scripts/modular-types",
+ ],
+ },
+ "create-modular-react-app": {
+ "location": "packages/create-modular-react-app",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "unknown",
+ "version": "4.0.0",
+ "workspaceDependencies": [],
+ },
+ "eslint-config-modular-app": {
+ "location": "packages/eslint-config-modular-app",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "unknown",
+ "version": "4.0.0",
+ "workspaceDependencies": [],
+ },
+ "modular-scripts": {
+ "location": "packages/modular-scripts",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "unknown",
+ "version": "4.0.1",
+ "workspaceDependencies": [
+ "@modular-scripts/modular-types",
+ "@modular-scripts/workspace-resolver",
+ ],
+ },
+ "modular-template-app": {
+ "location": "packages/modular-template-app",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "template",
+ "version": "1.2.0",
+ "workspaceDependencies": [],
+ },
+ "modular-template-esm-view": {
+ "location": "packages/modular-template-esm-view",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "template",
+ "version": "1.1.0",
+ "workspaceDependencies": [],
+ },
+ "modular-template-node-env-app": {
+ "location": "packages/modular-template-node-env-app",
+ "mismatchedWorkspaceDependencies": [],
+ "public": false,
+ "type": "template",
+ "version": "0.2.1",
+ "workspaceDependencies": [],
+ },
+ "modular-template-package": {
+ "location": "packages/modular-template-package",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "template",
+ "version": "1.2.0",
+ "workspaceDependencies": [],
+ },
+ "modular-template-source": {
+ "location": "packages/modular-template-source",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "template",
+ "version": "1.1.0",
+ "workspaceDependencies": [],
+ },
+ "modular-template-view": {
+ "location": "packages/modular-template-view",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "template",
+ "version": "1.2.0",
+ "workspaceDependencies": [],
+ },
+ "modular-views.macro": {
+ "location": "packages/modular-views.macro",
+ "mismatchedWorkspaceDependencies": [],
+ "public": true,
+ "type": "unknown",
+ "version": "3.1.1",
+ "workspaceDependencies": [],
+ },
+ "remote-view-demos": {
+ "location": "packages/remote-view-demos",
+ "mismatchedWorkspaceDependencies": [],
+ "public": false,
+ "type": "esm-view",
+ "version": "0.0.0",
+ "workspaceDependencies": [
+ "@modular-scripts/remote-view",
+ ],
+ },
+ "tree-view-for-tests": {
+ "location": "packages/tree-view-for-tests",
+ "mismatchedWorkspaceDependencies": [],
+ "public": false,
+ "type": "unknown",
+ "version": "2.0.1",
+ "workspaceDependencies": [],
+ },
}
`;
diff --git a/packages/modular-scripts/src/__tests__/utils/getWorkspaceInfo.test.ts b/packages/modular-scripts/src/__tests__/utils/getWorkspaceInfo.test.ts
index 7f85aac56..47365df69 100644
--- a/packages/modular-scripts/src/__tests__/utils/getWorkspaceInfo.test.ts
+++ b/packages/modular-scripts/src/__tests__/utils/getWorkspaceInfo.test.ts
@@ -2,11 +2,8 @@ import { getWorkspaceInfo } from '../../utils/getWorkspaceInfo';
test('getWorkspaceInfo', async () => {
const workspace = await getWorkspaceInfo();
- Object.entries(workspace)
- .sort(([packageA], [packageB]) =>
- packageA < packageB ? -1 : packageA > packageB ? 1 : 0,
- )
- .forEach(([, pkg]) => {
- expect(pkg).toMatchSnapshot({ version: expect.any(String) as unknown });
- });
+ Object.entries(workspace).forEach(([_, workspaceRecord]) => {
+ expect(typeof workspaceRecord.version).toBe('string');
+ });
+ expect(workspace).toMatchSnapshot();
});
diff --git a/packages/modular-types/src/types.ts b/packages/modular-types/src/types.ts
index 321dfc81c..af690375b 100644
--- a/packages/modular-types/src/types.ts
+++ b/packages/modular-types/src/types.ts
@@ -11,15 +11,17 @@ export type UnknownType = 'unknown';
export type ModularType = PackageType | UnknownType | 'root';
+export type ModularConfiguration = {
+ type: ModularType | undefined;
+};
+
export type ModularWorkspacePackage = {
path: string;
location: string;
name: string;
version: string;
workspace: boolean;
- modular?: {
- type: ModularType | undefined;
- };
+ modular?: ModularConfiguration;
type: ModularType | undefined;
children: ModularWorkspacePackage[];
parent: ModularWorkspacePackage | null;
@@ -27,6 +29,15 @@ export type ModularWorkspacePackage = {
rawPackageJson: ModularPackageJson;
};
+// Represents an exposed package.json that can be consumed via a RemoteView
+export type MicrofrontendManifest = {
+ name: string;
+ module: string;
+ style?: string;
+ styleImports?: string[];
+ modular?: ModularConfiguration;
+};
+
export interface WorkspaceDependencyObject {
workspaceDependencies: string[];
}
diff --git a/packages/remote-view-demos/README.md b/packages/remote-view-demos/README.md
new file mode 100644
index 000000000..008d9bb5b
--- /dev/null
+++ b/packages/remote-view-demos/README.md
@@ -0,0 +1,25 @@
+# RemoteView Demos
+
+This package contains demos of ``.
+
+The examples are a reference for users, but this package is also useful for
+developing `` components themselves.
+
+## Setup
+
+For demos using `` to work, we need some `esm-view`s that our
+RemoteView will render.
+
+To this end, `view1` and `view2` have been pre-built and are exposed in the fake
+ESM cdn that is also used in integration tests
+(`__fixtures/remote-view-fake-cdn`). These two views have been built pointing at
+esm.sh, which means that this demo only works with connectivity through to
+esm.sh. Note that the other packages in that directory are designed for use in
+integration tests.
+
+To run the demos, from the root of the monorepo:
+
+1. `node packages/remote-view/src/__tests__/serve.js` (boots a local static
+ content server on port 8484, exposing the pre-built views)
+2. `yarn modular start remote-view-demos` - launches the demos on
+ `localhost:3000`
diff --git a/packages/remote-view-demos/package.json b/packages/remote-view-demos/package.json
new file mode 100644
index 000000000..bcb489c07
--- /dev/null
+++ b/packages/remote-view-demos/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "remote-view-demos",
+ "private": true,
+ "modular": {
+ "type": "esm-view",
+ "externalCdnTemplate": "https://esm.sh/[name]@[version]"
+ },
+ "version": "0.0.0",
+ "dependencies": {
+ "@modular-scripts/remote-view": "*",
+ "@salt-ds/core": "1.1.0",
+ "@salt-ds/lab": "1.0.0-alpha.1",
+ "@salt-ds/theme": "1.0.0",
+ "react": "17.0.2",
+ "react-dom": "17.0.2"
+ }
+}
diff --git a/packages/remote-view-demos/src/App.tsx b/packages/remote-view-demos/src/App.tsx
new file mode 100644
index 000000000..991537f4d
--- /dev/null
+++ b/packages/remote-view-demos/src/App.tsx
@@ -0,0 +1,45 @@
+import React from 'react';
+import { H1, Text } from '@salt-ds/core';
+import {
+ HappyPathExample,
+ FallbackIframesExample,
+ DefaultErrorBoundaryExample,
+ CustomErrorContentExample,
+ CustomErrorBoundaryExample,
+ ErrorRecoveryExample,
+} from './examples';
+
+import './index.css';
+
+function RemoteViewDemos({
+ toggleThemeButton,
+}: {
+ toggleThemeButton: JSX.Element;
+}): JSX.Element {
+ return (
+
+
RemoteView demos
+
+ Showcase of implementing the micro-frontend pattern using{' '}
+ {''}.
+
+
+ Views loaded by {''} are Modular{' '}
+ ESM Views exposed over
+ HTTP. They also rely on loading dependencies from an{' '}
+ ESM CDN, which
+ happens at run-time.
+
+
+ {toggleThemeButton}
+
+
+
+
+
+
+
+ );
+}
+
+export default React.memo(RemoteViewDemos);
diff --git a/packages/remote-view-demos/src/examples/custom-error-boundary.tsx b/packages/remote-view-demos/src/examples/custom-error-boundary.tsx
new file mode 100644
index 000000000..d1c518c94
--- /dev/null
+++ b/packages/remote-view-demos/src/examples/custom-error-boundary.tsx
@@ -0,0 +1,42 @@
+import React, { useState } from 'react';
+import { MyErrorBoundary } from './my-error-boundary';
+import { RemoteView, RemoteViewProvider } from '@modular-scripts/remote-view';
+import { H2, Text } from '@salt-ds/core';
+import { Spinner } from '@salt-ds/lab';
+
+export function CustomErrorBoundaryExample() {
+ const [badView] = useState('http://localhost:8484/this-view-will-404');
+
+ return (
+
+
View not found (custom error boundary)
+
+ You can also bring your own error boundary for direct access to the
+ error. This allows implementing retry, reporting and other custom error
+ handling features.
+
+
+
+
+ You can render and do anything you want, it's just a React component.
+
+
+ Receives an error prop, which can be a{' '}
+ RemoteViewError or Error.
+
+
+ This error:
+
+ Name: {error.name}
+
+
+ Message: {error.message}
+
+
+
+ Re-mounting a RemoteViewProvider will cause any errors to
+ be removed and all child RemoteViews to be rendered from
+ scratch.
+
+ Hit the "Cause a crash" button, then "Recover".
+
+
+
+
+
+
{remoteViews[0]}
+
+ {showRecoveryView && (
+
+
+
+
+
+
+
+ )}
+
+
+
+
+ );
+}
diff --git a/packages/remote-view-demos/src/examples/fallback-iframes.tsx b/packages/remote-view-demos/src/examples/fallback-iframes.tsx
new file mode 100644
index 000000000..6476148f3
--- /dev/null
+++ b/packages/remote-view-demos/src/examples/fallback-iframes.tsx
@@ -0,0 +1,57 @@
+import React from 'react';
+import {
+ RemoteView,
+ RemoteViewErrorBoundary,
+ RemoteViewProvider,
+} from '@modular-scripts/remote-view';
+import { H2, Text } from '@salt-ds/core';
+import { Spinner } from '@salt-ds/lab';
+
+import type { MicrofrontendManifest } from '@modular-scripts/modular-types';
+
+export function FallbackIframesExample() {
+ const remoteViews = [
+ 'http://localhost:8484/view1',
+ 'http://localhost:8484/view2',
+ ];
+
+ function shouldUseIframe(manifest: MicrofrontendManifest) {
+ return ['view1', 'view2'].includes(manifest.name);
+ }
+
+ return (
+
+
Fallback iframe example
+
+ Implement loadWithIframeFallback to control any views that
+ should render in an iframe instead.
+
+
+
+ );
+}
diff --git a/packages/remote-view/src/components/default-unknown-error-fallback.tsx b/packages/remote-view/src/components/default-unknown-error-fallback.tsx
new file mode 100644
index 000000000..8d0d7f4a6
--- /dev/null
+++ b/packages/remote-view/src/components/default-unknown-error-fallback.tsx
@@ -0,0 +1,20 @@
+import React from 'react';
+
+interface Props {
+ error: Error;
+}
+
+/**
+ * Used to catch unknown errors, i.e. errors that are not RemoteViewErrors.
+ * This handles errors of any type within a tree, assuming the user is using the
+ */
+export function DefaultUnknownErrorFallback({ error }: Props) {
+ const { message } = error;
+
+ return (
+
+ Something went wrong
+ {message &&
{message}
}
+
+ );
+}
diff --git a/packages/remote-view/src/components/index.ts b/packages/remote-view/src/components/index.ts
new file mode 100644
index 000000000..81df3dd76
--- /dev/null
+++ b/packages/remote-view/src/components/index.ts
@@ -0,0 +1,3 @@
+export * from './remote-view';
+export * from './remote-view-provider';
+export * from './remote-view-error-boundary';
diff --git a/packages/remote-view/src/components/remote-view-error-boundary.tsx b/packages/remote-view/src/components/remote-view-error-boundary.tsx
new file mode 100644
index 000000000..21f22bcc3
--- /dev/null
+++ b/packages/remote-view/src/components/remote-view-error-boundary.tsx
@@ -0,0 +1,62 @@
+import React from 'react';
+import { RemoteViewError } from '../utils/remoteViewError';
+import { DefaultRemoteViewErrorFallback } from './default-remote-view-error-fallback';
+import { DefaultUnknownErrorFallback } from './default-unknown-error-fallback';
+
+interface BoundaryState {
+ error: RemoteViewError | Error | undefined;
+ isRemoteViewError: boolean | undefined;
+}
+
+interface BoundaryProps {
+ content?: React.ComponentType<{ error: RemoteViewError | Error }>;
+ children?: React.ReactNode;
+}
+
+export class RemoteViewErrorBoundary extends React.Component<
+ BoundaryProps,
+ BoundaryState
+> {
+ constructor(props: BoundaryProps) {
+ super(props);
+ this.state = { error: undefined, isRemoteViewError: undefined };
+ }
+
+ componentDidCatch(
+ error: Error | RemoteViewError,
+ errorInfo: React.ErrorInfo,
+ ): void {
+ const { message } = error;
+ console.error(message);
+ console.error(errorInfo.componentStack);
+
+ this.setState({
+ error,
+ isRemoteViewError: error instanceof RemoteViewError,
+ });
+ }
+
+ render() {
+ if (this.state.error) {
+ const ProvidedFallback = this.props.content;
+
+ // User-provided error boundary content
+ if (ProvidedFallback) {
+ return ;
+ }
+
+ // RemoteViewError specific error fallback
+ if (
+ this.state.isRemoteViewError &&
+ this.state.error instanceof RemoteViewError
+ ) {
+ return ;
+ }
+
+ // Error fallback for all other cases
+ return ;
+ }
+
+ return <>{this.props.children};
+ }
+}
diff --git a/packages/remote-view/src/components/remote-view-provider.tsx b/packages/remote-view/src/components/remote-view-provider.tsx
new file mode 100644
index 000000000..5181d255a
--- /dev/null
+++ b/packages/remote-view/src/components/remote-view-provider.tsx
@@ -0,0 +1,122 @@
+import React, { useState, useEffect, useMemo } from 'react';
+import { ErrorContext, ViewsContext } from '../context';
+import { RemoteViewError } from '../utils/remoteViewError';
+import { dynamicallyImport } from '../utils/dynamicallyImport';
+
+import type {
+ ManifestCheck,
+ RemoteViewErrorsContext,
+ RemoteViewsContext,
+} from '../types';
+import type { MicrofrontendManifest } from '@modular-scripts/modular-types';
+import { loading } from '../utils/symbol';
+
+interface Props {
+ children: React.ReactNode;
+ urls: string[];
+ loadWithIframeFallback?: ManifestCheck;
+}
+
+async function loadRemoteView(
+ baseUrl: string,
+ loadWithIframeFallback?: ManifestCheck,
+): Promise {
+ let manifest: MicrofrontendManifest | undefined;
+ try {
+ const response = await fetch(`${baseUrl}/package.json`);
+ manifest = (await response.json()) as MicrofrontendManifest;
+ } catch (e) {
+ throw new RemoteViewError(
+ `Unable to fetch and parse package.json for package at url "${baseUrl}"`,
+ baseUrl,
+ );
+ }
+ const type = manifest.modular?.type;
+ const unsupportedType = !type || (type !== 'esm-view' && type !== 'app');
+
+ if (unsupportedType) {
+ throw new RemoteViewError(
+ `Can't load package "${
+ manifest.name
+ }" at url "${baseUrl}" because type is missing or not supported: "${
+ type || JSON.stringify(type)
+ }"`,
+ baseUrl,
+ );
+ }
+
+ // Load with iframe if type is app or host decides to use fallback
+ if (
+ type === 'app' ||
+ (loadWithIframeFallback && loadWithIframeFallback(manifest))
+ ) {
+ const iframeTitle = manifest.name;
+ return () => ;
+ }
+
+ // Load global CSS
+ manifest.styleImports?.forEach(injectRemoteCss);
+
+ // Load microfrontend's local style
+ if (manifest.style) {
+ injectRemoteCss(`${baseUrl}/${manifest.style}`);
+ }
+
+ // Dynamically import ESM entrypoint
+ if (manifest.module) {
+ const LoadedView = await dynamicallyImport(baseUrl, manifest.module);
+
+ return LoadedView;
+ }
+}
+
+function injectRemoteCss(url: string) {
+ const node = document.head;
+
+ if (node.querySelector(`link[href="${url}"]`)) {
+ return;
+ }
+
+ /**
+ * should only be used to render content from a trusted source.
+ * `url` should never be the result of, or exposed to, end user input.
+ */
+ node.insertAdjacentHTML(
+ 'beforeend',
+ ``,
+ );
+}
+
+export const RemoteViewProvider = ({
+ children,
+ urls,
+ loadWithIframeFallback,
+}: Props): JSX.Element => {
+ const [views, setViews] = useState({});
+ const [errors, setErrors] = useState({});
+ const existingUrls = useMemo(() => Object.keys(views), [views]);
+ const dedupedUrls = useMemo(() => {
+ const allUrls = Array.from(new Set([...existingUrls, ...urls]));
+ return allUrls.filter((url) => !existingUrls.includes(url));
+ }, [urls, existingUrls]);
+
+ useEffect(() => {
+ for (const url of dedupedUrls) {
+ setViews((prev) => ({ ...prev, [url]: loading }));
+
+ void loadRemoteView(url, loadWithIframeFallback)
+ .then((LoadedView) => {
+ LoadedView && setViews((prev) => ({ ...prev, [url]: LoadedView }));
+ })
+ .catch((err: Error) => {
+ setErrors({ ...errors, [url]: err });
+ });
+ }
+ }, [dedupedUrls, setViews, loadWithIframeFallback, errors]);
+
+ return (
+
+ {children}
+
+ );
+};
diff --git a/packages/remote-view/src/components/remote-view.tsx b/packages/remote-view/src/components/remote-view.tsx
new file mode 100644
index 000000000..029c69a99
--- /dev/null
+++ b/packages/remote-view/src/components/remote-view.tsx
@@ -0,0 +1,18 @@
+import React from 'react';
+import { useRemoteView } from '../hooks/useRemoteView';
+
+interface Props {
+ url: string;
+ loading?: JSX.Element;
+}
+
+function DefaultLoading() {
+ return