Use portal functions

A portal function is a declared host capability callable by a widget worker. Import functions from @fluid-app/portal-sdk/widgets/worker and declare every function the widget uses. The callable exports are under Variables in the Widget Worker SDK Reference.

Declare each function in `uses`

import {
  defineWidget,
  getPortalProfile,
  navigateTo,
} from "@fluid-app/portal-sdk/widgets/worker";

export const profileCard = defineWidget({
  name: "ProfileCard",
  component: ProfileCard,
  uses: [getPortalProfile, navigateTo],
});

Call the same typed function values from the component. Do not maintain a parallel string list of capability names. The worker and host enforce the uses declaration.

Choose a capability family

The public worker facade provides functions for:

portal navigation, links, fullscreen, account, store, and profile state;
content, catalog, media, metric, and calendar reads;
content, playlist, share, and DAM mutations;
member access, points, todos, account updates, and MySite data.

Use each linked generated declaration for the function’s exact input, result, error behavior, and required uses declaration. For example, see getPortalProfile and navigateTo.

Handle errors and partial data

import { PortalFunctionError } from "@fluid-app/portal-sdk/widgets/worker";

try {
  const profile = await getPortalProfile();
  // Render the documented profile data.
} catch (error) {
  if (error instanceof PortalFunctionError) {
    // Render a recoverable unavailable state.
  }
  throw error;
}

Treat results as documented SDK values and do not assume undocumented fields are present. Handle unavailable, missing, partial, and malformed values without throwing during render. See PortalFunctionError for the supported error codes. A widget has no server, database or secrets of its own. When it needs its own data model or API, put that in a server app, such as a Mist app, which comes with hosting and a Postgres database. The widget then reaches the server through a portal function that your portal implements. The worker can’t call the server directly. Even with network access, a widget’s requests to fluid.app addresses, including Mist app addresses, are blocked. So the call runs in the portal, which owns the handler.

Define the function

Define it once, in a module that both the widget and the portal import. Inputs and outputs must be JSON values.

// src/functions/attendance.ts
import { definePortalFunction } from "@fluid-app/portal-sdk/widgets/worker";

export const listAttendance = definePortalFunction<
  { events: { name: string; attended: number }[] },
  { month: string }
>({
  capability: "company.event-attendance",
  version: "1",
  method: "list",
});

Call it from the widget

Add the function to the widget’s uses, then call it like any other portal function.

export const attendanceWidget = defineWidget({
  name: "EventAttendance",
  component: EventAttendance,
  uses: [listAttendance],
});

// In the component
const { events } = await listAttendance({ month: "2026-10" });

Implement it in the portal

In the portal project’s src/main.tsx, pass a handler for the function to createPortal. The handler calls your server.

import { createPortal, implementPortalFunction } from "@fluid-app/portal-sdk";
import { listAttendance } from "./functions/attendance";

createPortal({
  remoteWidgets: {
    functions: [
      implementPortalFunction(listAttendance, async ({ month }) => {
        const response = await fetch(
          `https://event-attendance.mist.fluid.app/api/attendance?month=${month}`,
        );
        return response.json();
      }),
    ],
  },
});

Keep secrets on the server, never in the portal code. Your server receives requests from the portal page, so it must allow your portal’s address and check every request itself. See Mist app authentication. A custom function works only in a portal that implements it. This pattern suits a company package, whose widgets and portal live in the same project. In a portal without the handler, the call rejects with a PortalFunctionError, so render a useful unavailable state.

Get started

Sites

Mist apps

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Use portal functions

Declare each function in `uses`

Choose a capability family

Handle errors and partial data

Give a widget its own backend

Declare each function in uses

Choose a capability family

Handle errors and partial data

Give a widget its own backend

Declare each function in `uses`