Micro-Frontend Development Setup

This guide covers three ways to develop and verify the micro-frontends in this repository: run the sample-data demo by itself, connect WebOC to the published demo, or connect WebOC to a locally running micro frontend.

Standalone Demo with Sample Data

The demo runs without WebOC or a FEWS server. It provides the host contexts used by the components and serves sample data from the micro-frontends package.

From the repository root, start the demo:

npm run -w @deltares/fews-web-oc-micro-frontends demo

Open http://localhost:2010. The demo landing page links to the available sample views. This mode is useful for component work and visual checks; it runs the demo app directly rather than loading the component as a federated remote in WebOC.

Run WebOC dev mode with the Published Demo

Use this setup to develop WebOC while loading the published micro-frontend remote. Its manifest is mf-manifest.json.

Configure the WebOC remote as follows:

{
	"name": "delft-fews-weboc",
	"remotes": [
		{
			"name": "test-micro-frontend",
			"entry": "https://deltares.github.io/fews-web-oc-components/micro-frontend-demos/mf-manifest.json"
		}
	]
}

In the WebOC repository, create or update .env.development with the manifest path used by that WebOC development setup and allow the published origin through its development CSP:

VITE_FEWS_WEBSERVICES_URL=http://localhost:8080/FewsWebServices/

VITE_FEWS_WEBOC_MF_MANIFEST_URL=/mf-manifest-github.json
DEV_CSP_CONNECT_SRC=https://deltares.github.io
DEV_CSP_SCRIPT_SRC=https://deltares.github.io
DEV_CSP_FONT_SRC=https://deltares.github.io
DEV_CSP_STYLE_SRC=https://deltares.github.io

Set VITE_FEWS_WEBSERVICES_URL to the Web Services URL for the FEWS instance you want to use. For a standalone FEWS instance with Web Services running locally, use http://localhost:8080/FewsWebServices/, as shown; you can instead use the URL of a hosted FEWS Web Services instance. This setting applies to both WebOC development setups below.

The /mf-manifest-github.json file comes standard with the WebOC repository and points to the published manifest linked above. Start WebOC using its development command; restart it after changing .env.development.

Run WebOC dev mode with a Micro Frontend dev mode

Run the federated micro-frontend dev server from this repository root:

npm run dev:mf

The Vite server runs on port 2010 and serves the development manifest at http://localhost:2010/mf-manifest.json. In the WebOC repository, point its development environment at that manifest and allow the local remote through CSP:

VITE_FEWS_WEBSERVICES_URL=http://localhost:8080/FewsWebServices/

VITE_FEWS_WEBOC_MF_MANIFEST_URL=http://localhost:2010/mf-manifest.json
DEV_CSP_CONNECT_SRC=http://localhost:2010
DEV_CSP_SCRIPT_SRC=http://localhost:2010
DEV_CSP_FONT_SRC=http://localhost:2010
DEV_CSP_STYLE_SRC=http://localhost:2010

Start WebOC in development mode as well. Keep the micro-frontend dev server running while using WebOC; changes to the remote are served by Vite. If the component calls FEWS services directly, ensure their origins are also allowed by WebOC's connect-src policy.

Scaffold a Vite Micro Frontend

Create a Vue 3 project with the Vite TypeScript template, then install the Module Federation Vite plugin:

npm create vite@latest my-micro-frontend -- --template vue-ts
cd my-micro-frontend
npm install
npm install @module-federation/vite

Create module-federation.config.ts in the project root. This example exposes the HelloWorld.vue component generated by the Vue template; replace the exposed path and key with the component you want WebOC to load:

import { createModuleFederationConfig } from '@module-federation/vite'

export default createModuleFederationConfig({
	name: 'my-micro-frontend',
	filename: 'remoteEntry.js',
	manifest: true,
	exposes: {
		'./hello_world': './src/components/HelloWorld.vue',
	},
	shared: {
		vue: { singleton: true },
	},
})

Update vite.config.ts to register the federation plugin alongside Vue, and pin the local remote to port 2010 so it does not conflict with WebOC's port 5173:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { federation } from '@module-federation/vite'
import mfConfig from './module-federation.config.ts'

export default defineConfig({
	plugins: [vue(), federation(mfConfig)],
	server: {
		port: 2010,
		strictPort: true,
	},
})

Start the remote with npm run dev. Its manifest is available at http://localhost:2010/mf-manifest.json; use that URL for the remote entry in WebOC's development configuration. The federation name must match the remote name registered by the host, and the expose key (for example, ./hello_world) must match the module requested by the host.

Development CSP

WebOC applies Content Security Policy in development mode. The DEV_CSP_* values above allow the respective resource types from the remote origin; use the GitHub origin for the published demo and the local Vite origin for local development. Preserve any other origins required by the WebOC app or its services when configuring these values.