Set Up an Embedded UI Module

This guide walks through embedding a single Unqork module in an external web page using the Embedded UI. By the end, a working module renders inside the host page without redirecting the end-user or affecting the host page's styles.

Prerequisites

Complete these steps before beginning:

An Unqork environment with the Embedded UI feature enabled. The embedded.js script returns a 404 error if the feature is not active on the environment.
The host page domain added as a CORS exception in Environment Administration > Cross-Origin Resource Sharing (CORS). Browsers block cross-origin API requests by default. Without this exception, the runtime cannot reach the Unqork API from the host page.
A published module with a known module ID. The runtime fetches the module definition by its 24-character MongoDB ObjectId. Unpublished modules are not accessible.

Step 1: Add the Embedded Script

Add a single <script> tag to the host page pointing to the Unqork environment's embedded.js endpoint. Loading this script creates window.unqork, the entry point for all runtime API calls. Without it, the runtime object does not exist and no modules can mount.

<script src="https://your-environment.unqork.io/embedded.js"></script>

Note: The script must load after the DOM is ready. Place the script tag at the end of <body> or use the defer attribute.

Step 2: Add a Mount Target

Add an element to the host page where the module will render. The runtime registers it as a Shadow DOM web component, keeping styles isolated between the module and the host page. The tag name can be any hyphenated name not already registered as a custom element.

<unqork-app></unqork-app>

Step 3: Initialize and Mount

Write a script that initializes the runtime and mounts the module. Always call initialize() before mountModule(). The runtime must complete its internal setup before it can load a module. Calling mountModule() first returns an error.

<script>
  (async () => {
    const runtime = window.unqork.runtimes.default
    await runtime.initialize()
    await runtime.mountModule({
      moduleId: '696f9c76f9325e1f580152c7',
      target: 'unqork-app'
    })
  })()
</script>

Parameter	Description
`moduleId`	The MongoDB ObjectId of the module to embed.
`target`	The custom element tag name (for example, `unqork-app`) where the module renders.

Step 4: Add Error Handling (Optional)

The embedded runtime does not surface errors to the host page. It dispatches them as custom DOM events instead. Without a listener, errors occur silently and the module stops working with no explanation.

<script>
  window.addEventListener('unqork-embed-error', (event) => {
    console.error('Embed error:', event.detail.type, event.detail.message)
  })
</script>

Step 5: Add Authentication (If Required)

Modules with access controls reject unauthenticated requests with a 401 or 403 error. Checking the authentication status before mounting prevents a visible error state when the module first loads.

<script>
  (async () => {
    const runtime = window.unqork.runtimes.default
    await runtime.initialize()

    if (!(await runtime.isAuthenticated())) {
      await runtime.authenticateAnonymous({ moduleId: 'abc123' })
    }

    await runtime.mountModule({ moduleId: 'abc123', target: 'unqork-app' })
  })()
</script>

Complete Example

The following is a minimal but complete host page that embeds a module with error handling.

<!DOCTYPE html>
<html>
<head>
  <title>My App with Unqork Module</title>
</head>
<body>
  <h1>My Application</h1>
  <unqork-app></unqork-app>
  <a href="https://google.com" target="_blank">External Link (still works)</a>

  <script src="https://my-unqork-env.unqork.io/embedded.js"></script>
  <script>
    window.addEventListener('unqork-embed-error', (event) => {
      console.error('Embed error:', event.detail.type, event.detail.message)
    })

    ;(async () => {
      const runtime = window.unqork.runtimes.default
      await runtime.initialize()
      await runtime.mountModule({
        moduleId: '696f9c76f9325e1f580152c7',
        target: 'unqork-app'
      })
    })()
  </script>
</body>
</html>

Changelog

Date	Change
2026-06-08	Added "why" context to Prerequisites, Steps 1–5.
2026-04-21	Initial publication.

Documentation Index