Development

What is dev mode?

Dev mode is a development feature that allows you to preview widgets using non-production code directly within Foundry applications. When dev mode is active, your development server (running either locally or in Foundry) overrides the published widget assets, letting you see your code changes in real-time without needing to publish a new version.

Key characteristics of dev mode:

• Personal: Only affects your user account and other users continue to see the published version.
• Temporary: Automatically expires after 24 hours.
• Live updates: Code changes from your development server immediately appear in the widget.
• Context-aware: Works in both the custom widgets playground and host applications like Workshop.

Set up a project

If you chose to use a Foundry Code Repository to store your source code, first follow the "Work locally" instructions in VS Code Workspace or the Code Repositories application to clone the repository to your local machine.

Set the FOUNDRY_TOKEN environment variable in your terminal with a user-generated token with the following command, or the equivalent for your operating system.

Copied!
1
export FOUNDRY_TOKEN=<token>

In the project directory, run the following commands to install dependencies and start the dev server:

Copied!
1
2
npm install
npm run dev

A link will be printed to the terminal which you can open to set up dev mode for your widget set. This will redirect the browser to the widget set overview page once complete, from which you can select a widget to start developing against. The live code running from your development server will now be displayed in the widget playground and any changes to your code will immediately update the widget on the page.

Dev mode environments

Once your dev server is running, you can preview your widgets in the different environments outlined below.

Custom widgets playground

The custom widgets playground is a dedicated development environment for testing individual widgets which provides:

• Isolated testing: Preview widgets in different dimensions and configurations.
• Parameter controls: Interactive controls to test widget parameters you have defined.
• Event monitoring: A message log showing widget events and parameter updates from Foundry.
• Dev mode integration: When dev mode is active, the playground displays your development code.

Workshop integration

When developing Workshop widgets, dev mode extends beyond the playground to actual Workshop applications. This allows you to:

• Preview widget changes in the full context where the widget will be used
• Test interactions with other Workshop components
• Validate the widget's behavior in real application scenarios

VS Code Workspaces limitation

Previewing changes from a dev server running in VS Code Workspaces is currently unsupported. Follow the instructions that appear in the VS Code preview panel to "Work locally" and run the dev server on your local machine.

Dev mode controls and states

Dev mode can be controlled through the custom widgets playground interface. The controls indicate the current state and allow you to enable, disable, or pause dev mode as needed.

Disabled state (default)

Dev mode is disabled by default. You can enable it through the playground controls, but it will remain inactive unless your dev server is running and has overrides for the current widget.

Enabled state

When active, dev mode displays content from your development server instead of the published widget version. This state confirms that your local changes are being previewed.

Enabled (inactive) state

This state indicates dev mode is enabled but no development server overrides exist for the current widget, so the published version is still displayed. This typically happens when your dev server is not running or does not include the widget you are viewing.

Paused state

The paused state temporarily disables dev mode while keeping the controls visible in host applications like Workshop, making it easy to resume development when needed.

Add and modify parameters and events

The parameters and events for a widget are typically defined in a main.config.ts file. This is type-safe so adding or modifying parameters and events can be done easily without errors.

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
34
// main.config.ts
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"],
    },
  },
});

Unsupported features

The custom widgets runtime does not support certain browser APIs for persisting data such as:

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

To share state between multiple widgets on the page, use parameters configured through the host application (for example, variables in Workshop). To persist state, you may use saved states for Workshop variables, or write data to the ontology.

Non-Ontology APIs are also not supported in the custom widgets runtime.