Example MFE (Suncoast Contract)

Example micro-frontend package that:

• follows the Suncoast UI module contract (module.definition.json)
• includes a host adapter for the current shell CmsModuleDefinition contract
• builds to a single browser JS file (dist/example-mfe.js)
• provides Directus seed data for cms_modules
• demonstrates GraphQL async communication:
  • submit via GraphQL HTTP mutation
  • receive streamed response via GraphQL WS subscription

Quick Start

npm install
npm run dev

Local preview URL:

• http://localhost:4173/preview/ (default)

Build production artifact:

npm run build

Build output:

• dist/example-mfe.js (single-file bundle)
• dist/example-mfe.js.map
• dist/module.definition.json

GraphQL Runtime Configuration

GraphQL endpoint/token values are runtime-resolved. They are not baked into the built bundle.

Resolution order:

1. props.graphql.* from CMS block config
2. Shell runtime values (#cms-root data attrs / window.__SUNCOAST_RUNTIME__.graphql)
3. Browser auth storage fallback for token (for preview helper flows)

Local preview:

1. Copy .env.local.example to .env.local
2. Set optional preview auth values
3. Run npm run dev

Supported env vars:

• MFE_PREVIEW_AUTH_ISSUER_URL (preview login default, usually https://auth.suncoast.systems)
• MFE_PREVIEW_AUTH_CLIENT_ID (preview login client id)
• MFE_PREVIEW_AUTH_AUDIENCE (preview login audience, optional)
• MFE_PREVIEW_AUTH_SCOPE (preview login scope, default openid profile email)
• MFE_PREVIEW_PORT (dev only)

Local Preview Login

The local preview page (/preview/) now includes a login helper that runs OAuth/OIDC code+PKCE in-browser:

1. Fill Auth Issuer URL and Auth Client ID (or set MFE_PREVIEW_AUTH_* env vars).
2. Click Login on the preview page.
3. After redirect back to /preview/, the access token is auto-filled into Auth Token.
4. Click Apply / Remount to use that token for GraphQL HTTP/WS requests.

If your auth provider returns access_token in URL hash (implicit flow), the preview page will capture that too.

What This MFE Does

• Module key: mfe-example-chat
• Renders a simple textbox + submit button chat UI
• Submits prompts using GraphQL mutation publish_async_request
• Listens for response row updates from graphql.client_async_messages over GraphQL subscription
• Emits module events

Directus Setup

1. Host dist/example-mfe.js at a URL reachable by your shell runtime.
2. Create/update a cms_modules record using directus/cms-module.seed.json.
3. In a cms_block_module block, choose module key mfe-example-chat.
4. Use directus/cms-block-module.props.example.json as your props_json baseline.
5. Set:
   • optional graphql.httpUrl and graphql.wsUrl overrides (leave unset to use shell runtime defaults)
   • optional graphql.authToken override (usually leave unset and let shell runtime auth provide token)
   • graphql.submitMutation and graphql.streamSubscription (defaults are preconfigured for publish_async_request + graphql_client_async_messages)
   • path mappings:
     • graphql.submitRequestIdPath
     • graphql.streamTextPath
     • graphql.streamDonePath
     • graphql.streamErrorPath

Automated Registry Publish (No Directus/GitOps PR Required)

publish.yml now publishes module artifacts directly to the module registry service POST /v1/modules/publish using multipart upload.

1. Add repository variable(s) or secret(s):
   • MODULE_REGISTRY_SERVICE_URL_PREVIEW
   • MODULE_REGISTRY_SERVICE_URL_PROD
   • optional legacy fallback: MODULE_REGISTRY_SERVICE_URL
2. Add repository secrets for module registry publish API auth:
   • MODULE_REGISTRY_SERVICE_GOOGLE_SERVICE_ACCOUNT_EMAIL
   • MODULE_REGISTRY_SERVICE_GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY
   • MODULE_REGISTRY_SERVICE_GOOGLE_TOKEN_AUDIENCE
3. Optional repository variable:
   • MODULE_REGISTRY_SERVICE_PUBLISH_PATH (default /v1/modules/publish)
4. Publish tag v* (or run Publish workflow manually).
5. Workflow will:
   • build artifacts
   • run npm run publish:registry to generate dist/module.publish.json
   • run npm run notify:catalog to upload dist/example-mfe.js and dist/module.publish.json to the registry service
   • attach release artifacts in GitHub

publish:registry writes metadata in dist/module.publish.json:

• module_version
• published_at
• release.tag
• release.sha
• bundle.sha256
• full definition + seed documents

Module registry service endpoint called by workflow:

• POST <resolved-service-url><MODULE_REGISTRY_SERVICE_PUBLISH_PATH>
• Default path: /v1/modules/publish
• Channel defaults:
  • tag publish: prod
  • manual publish: preview (override via workflow input module_channel)
• Service URL selection:
  • prod channel: MODULE_REGISTRY_SERVICE_URL_PROD then fallback MODULE_REGISTRY_SERVICE_URL
  • preview channel: MODULE_REGISTRY_SERVICE_URL_PREVIEW then fallback MODULE_REGISTRY_SERVICE_URL

Important Runtime Note

This repo provides the MFE contract + bundle. Your shell runtime must include or load this module definition at runtime.

If your shell currently only mounts modules from an internal registry, wire this module using the exported host adapter:

• export: createCmsModuleDefinition()

The bundle also self-registers at:

• globalThis.SuncoastMfeRegistry["mfe-example-chat"]

Scripts

• npm run clean - remove dist
• npm run clean:dev - remove dev-dist
• npm run typecheck - TS type check
• npm run build - compile single JS + copy module definition
• npm run dev - local preview server with live rebuild + preview harness
• npm run publish:registry - generate local publish manifest from built artifacts
• npm run notify:catalog - upload built bundle + publish manifest to module registry API
• npm run sync:directus - direct Directus upsert (optional; only if network access exists)

GitHub Actions

Workflows included:

• .github/workflows/ci.yml
  • runs typecheck/build on push + PR
  • uploads dist artifacts
• .github/workflows/publish.yml
  • runs on v* tags or manual dispatch
  • builds bundle + publish metadata
  • uploads artifacts
  • creates a GitHub Release for tag pushes

Secrets expected by publish workflow:

• MODULE_REGISTRY_SERVICE_GOOGLE_SERVICE_ACCOUNT_EMAIL
• MODULE_REGISTRY_SERVICE_GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY
• MODULE_REGISTRY_SERVICE_GOOGLE_TOKEN_AUDIENCE

Repository variables used by publish workflow:

• MODULE_REGISTRY_SERVICE_URL_PREVIEW
• MODULE_REGISTRY_SERVICE_URL_PROD
• MODULE_REGISTRY_SERVICE_URL (legacy fallback)
• MODULE_REGISTRY_SERVICE_PUBLISH_PATH (optional, default /v1/modules/publish)