Przejdź do głównej zawartości
Dokumentacja

Embed the workspace UI in a React app

Ta treść nie jest jeszcze dostępna w Twoim języku.

This guide mounts an Overvis HMI workspace, with its dashboards and Setup pages, in your own React application. For dashboard development, the project that hmi pull generates is simpler: it already serves dashboard sources and proxies the API; see Pull a workspace. The package is described in @overvis/hmi-workspace-ui.

Install the package

Section titled “Install the package”

  1. Use Node.js 22.13+ on the 22.x line, or 23.4+, for the build tooling.

  2. Install the library and its peers, in versions that satisfy the package’s peer ranges:

    Terminal window
    pnpm add @overvis/hmi-workspace-ui react react-dom @tanstack/react-form @tanstack/react-query @tanstack/react-router @trpc/client @trpc/react-query @trpc/server
    pnpm add -D @types/react @types/react-dom

  3. If the application also builds dashboards with hmi build, add Vite, Tailwind CSS, @vitejs/plugin-react, @tailwindcss/vite, and TypeScript.

Mount a workspace

Section titled “Mount a workspace”

  1. Get a workspace API key: pulling the workspace creates one (Workspace settings → General → Develop locally). The kinds of keys are described in the API overview.

  2. Mount LocalWorkspaceApp at the application root:

    import { createRoot } from "react-dom/client";
    import { LocalWorkspaceApp } from "@overvis/hmi-workspace-ui/host";
    import { initializeLocale } from "@overvis/hmi-workspace-ui/i18n";
    import "@overvis/hmi-workspace-ui/styles.css";
    

    await initializeLocale();
    

    const root = document.getElementById("root");
    if (root) {
      createRoot(root).render(
        <LocalWorkspaceApp
          apiUrl="/"
          apiKey="YOUR_WORKSPACE_API_KEY"
          workspaceId="YOUR_WORKSPACE_UUID"
        />,
      );
    }

  3. Replace the placeholders with the workspace API key and the workspace UUID.

    The key ends up in the page’s JavaScript: anyone who can open the application can read it and use it with its permissions. Serve the application only to people who may use that key, for example on your own computer, or keep the key on a server of yours that adds it to API requests.

  4. Serve the API on the application’s origin and set apiUrl to /: proxy requests under /trpc and /static to the Overvis HMI API, as the development server of a pulled project does. Published dashboards and rendered reports load from /static. LocalWorkspaceApp appends /trpc itself. The API does not accept browser requests from other origins.

Show action messages

Section titled “Show action messages”
  1. Wrap the UI in MessageHistoryProvider with the signed-in user’s ID as identity. Give each user a different identity; without one, history is kept in memory only.
  2. Place MessageHistoryBell in the header.
  3. Wrap each workspace’s UI in MessageScopeProvider with { workspaceId, workspaceName }.
  4. In components, call useToast() and use its success, info, warning, or error method. In an asynchronous action, take the helper before the action starts, so its completion message keeps the original workspace. Prefer useToast over the legacy toast export in new code.
  5. To add server notifications to the same bell, pass notifications and notificationUnreadCount.
Section titled “Related”