Develop and preview a widget set

Use dev mode to preview unpublished widget code in Foundry while you develop. Dev mode replaces the published assets for your user account only, so other users continue to see the published version.

This page explains how to start a development server, connect it to your widget set, and confirm that Foundry is displaying your changes.

Before you begin

You need a widget set and its source code. If you have not created one, follow Create a widget set first.

Choose where you want to run the development server:

Start a development session

Develop on your local machine

1. Clone the widget set's code repository. For a Foundry Code Repository, follow the Work locally instructions in VS Code Workspaces or the Code Repositories application.

2. Create a user-generated token.

3. In a terminal, set the FOUNDRY_TOKEN environment variable. Replace <token> with your token.

   Copied!
   1
   export FOUNDRY_TOKEN=<token>

4. From the project directory, install the project dependencies.

   Copied!
   1
   npm install

5. Start the local development server.

   Copied!
   1
   npm run dev

6. Keep the development server running and open the setup link printed in the terminal. The link connects the server to your widget set and opens the widget set overview page.

7. Select a widget to open it in the custom widgets playground.

8. Edit and save a source file. The playground updates with your development version.

If the widget does not update, first confirm that the terminal still shows a running development server and that you opened the most recent setup link.

Develop in a VS Code workspace

1. Open the widget set's code repository in a VS Code workspace.

2. Wait for the workspace to start. The development server starts automatically for widget set templates.

3. If the server is not running, start it from the project directory.

   Copied!
   1
   npm run dev:remote

4. In the VS Code preview panel, select the widget that you want to preview.

5. Edit and save a source file. The preview panel updates with your development version.

The same workspace development server can provide overrides to the custom widgets playground and Workshop. You do not need to run a second server.

Confirm that dev mode is active

Dev mode controls show which version of a widget you are viewing:

Start dev mode

When dev mode is disabled, the Start dev mode control is displayed. Start your development server before selecting the control so that dev mode can find the widget overrides.

Understand an inactive session

An inactive session means that your development server has no overrides for the widget you are viewing. This state does not always need to be resolved. For example, dev mode reports an inactive session when you open a widget from a different widget set to compare it, or when you view a Workshop application in which you are developing only some of the custom widgets. In these cases, the published version is the version you expect to see.

If you do intend to develop the widget you are viewing, start the development server, confirm that it includes the widget, and then reapply dev mode.

Resume or stop a paused session

Select Resume to display the development version again. Select Stop to end the dev mode session and continue using the published version.

Identify the development source

An active local session identifies localhost as its source:

An active VS Code Workspaces session identifies the workspace as its source:

Dev mode is personal and temporary. It does not change what other users see, and it expires after 24 hours.

Choose a preview environment

After dev mode is active, use the environment that matches what you need to test:

The playground displays controls for parameters and a message log for events:

Workshop displays the development version in the application where you use the widget:

Preview different types of changes

Dev mode handles source code and widget configuration changes differently:

Add or modify parameters and events

Widget templates define parameters and events in a configuration file such as main.config.ts. The following example defines three parameters and two events:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "<Widget ID>", // The unique identifier of the widget within your project
  name: "<Widget Name>", // A user friendly name for your widget
  description: "<Widget Description>", // A user friendly description of your widget
  type: "workshop",
  parameters: {
    headerText: {
      displayName: "Widget title",
      type: "string",
    },
    showWarning: {
      displayName: "Show warning callout",
      type: "boolean",
    },
    todoItems: {
      displayName: "Todo items",
      type: "array",
      subType: "string",
    },
  },
  events: {
    updateHeader: {
      displayName: "Update header",
      parameterUpdateIds: ["headerText"],
    },
    updateTodoItems: {
      displayName: "Update todo items",
      parameterUpdateIds: ["todoItems"],
    },
  },
});

Dev mode can preview parameter and event changes with @osdk/widget.vite-plugin version 3.34.0 or later. For supported types and examples of reading parameters and emitting events from a widget, see Parameters and events.

Understand runtime limitations

Browser storage

The custom widgets runtime does not support browser APIs that persist data, including:

• Web Storage API ↗ (localStorage and sessionStorage)
• IndexedDB API ↗

To share state between widgets, use parameters configured through the host application, such as Workshop variables. To persist state, use saved states for Workshop variables or write data to the Ontology.

Widget state in Workshop

By default, Workshop unmounts custom widgets when they leave the screen. This discards state held in the widget's iframe. To preserve local state across navigation, configure widget display optimization to keep the widget mounted.

Network requests

The custom widgets runtime uses a restrictive content security policy that you cannot configure. The runtime blocks external requests and does not support non-Ontology APIs. To access an external service, use a Foundry resource that wraps the request, such as a function or webhook.

Theming

You can use CSS media queries and JavaScript to detect the parent application's color scheme. For implementation details and examples, see Dark theme support.

Troubleshooting

For help with browser crashes, performance problems, or unexpected behavior while developing custom widgets, see Troubleshooting.