This package supports development of widgets built using the Widget Development Kit

This package is part of the Widget Development Kit, which is a collection of NPM packages that empower developers to create widgets for Bloom Intranet.

@ichicraft/widgets-widget-base

The contract a widget implements, and the shape of what the Widget Board hands it at runtime. A widget extends BaseWidget, receives a WidgetContext, and renders into a DOM element the board owns.

Features

• One base class — Extend BaseWidget, implement init and render, and the board takes care of the rest
• Opt-in capabilities — Buddy rendering, user and admin configuration, import and export are optional methods; implement only what the widget needs
• A scoped context — WidgetContext exposes the SharePoint and Graph clients, the current user, the board's theme and the host environment, without handing over the web part
• Dev server helpers — lib/dev builds a webpack dev-server configuration that resolves its own port, so several widgets can be debugged against one board at once

Installation

npm install @ichicraft/widgets-widget-base

Usage

A widget is a class extending BaseWidget. Only init and render are required.

import { BaseWidget, type WidgetContext } from '@ichicraft/widgets-widget-base';

export default class RssWidget extends BaseWidget {
    private feed: FeedItem[] = [];

    public async init(): Promise<void> {
        // Called once before the first render. Fetch what the widget needs.
        this.feed = await loadFeed(this.context.instance.data);
    }

    public render(domElement: HTMLDivElement): void {
        // Called whenever the board wants the widget drawn.
        ReactDOM.render(<Rss items={this.feed} context={this.context} />, domElement);
    }
}

this.context is the WidgetContext the board constructed for this widget instance.

Optional capabilities

Each of these is optional. Implementing one tells the board the widget supports that capability.

| Method | Purpose | | --- | --- | | renderBuddy(el, options?) | Draw the widget's buddy-bar entry. Return true when rendering it yourself. options.allowRichRendering says whether the slot has room for more than an icon button. | | renderUserConfigurationForm(el) | Draw the per-user settings form. | | validateUserConfigurationForm() | Return a ValidationResult before the form is saved. | | getSerializedUserConfiguration() | Return the form's state as the string the board persists. | | verifyPersistedUserConfiguration(config) | Check stored configuration before it is used. | | renderAdminConfigurationForm(el) and its siblings | The same four methods for the admin-level configuration. | | exportData() / importData(data) | Move the widget's stored data between boards. | | updateDataAccess(from, to) | React to the widget's audience changing. | | cleanupResources() | Release anything held when the widget is torn down. |

What is on the context

WidgetContext is broad; these are the parts most widgets reach for.

// SharePoint and Graph, already authenticated for this user
context.sp; // @pnp/sp SPFI
context.spHttpClient; // SPHttpClient
context.msGraphClient; // Graph client
context.aadHttpClientFactory; // for your own AAD-protected APIs

// Who is looking at it
context.userDisplayName;
context.userEmail;
context.spUserId;
context.userRoles; // 'administrator' | 'board-owner' | 'widget-administrator'
context.language;

// Where it is running
context.siteUrl;
context.tenantId;
context.inTeamsContext;
context.isMobileBrowser;
context.assetsBaseUrl; // the folder this widget's bundle was loaded from

// This placement and its configuration
context.instance; // this instance: id, parent board, deep links, notifications
context.instance.data; // user settings for this instance, as a string
context.variant.data; // board-wide settings for it, as a string
context.instance.cache; // a CacheManager scoped to this instance
context.variant.cache; // a CacheManager scoped to the variant
context.manifest; // what the widget declared about itself
context.design; // the board's theme colours

The full set is in WidgetContext in lib/types; the interface is documented member by member.

Reading configuration

Configuration is persisted as a string. ConfigurationHelper parses it back.

import { ConfigurationHelper } from '@ichicraft/widgets-widget-base/lib/utils';

const config = ConfigurationHelper.parseConfiguration<RssConfig>(this.context.instance.data);

parseConfiguration returns an empty object rather than throwing when the stored value is empty. instance.data holds the settings a user made for this placement; variant.data holds the board-wide ones an administrator configured.

Debugging against a live board

lib/dev builds the webpack dev-server configuration for a widget, resolving a free port first so the manifest url handed to the board always matches the port the server binds to. That is what allows several widgets to be debugged on one board at the same time.

// webpack.dev.ts
import { createWidgetDevServerConfig } from '@ichicraft/widgets-widget-base/lib/dev';
import serveConfig from './config/serve.config';

const { devServer, cssModuleLocalIdentName, manifestUrl, debugPageUrl } =
    await createWidgetDevServerConfig({ projectPath: __dirname, serveConfig });

serve.config.ts controls the session:

export default {
    widgetsDebugPageUrl: 'https://contoso.sharepoint.com/sites/intranet/SitePages/Home.aspx',
    debugPort: 8081, // optional; otherwise the first free port from 8080 up
    openBrowser: false, // set false for the second and further widgets in a session
};

cssModuleLocalIdentName is keyed by port, so two widgets served at once never collide on css module class names.

webpack and webpack-dev-server are optional peer dependencies. They are only needed for these helpers, which every widget project already has installed.

Changelog

All notable changes to this project will be documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Entries from 1.21.0 onwards are generated from pull request descriptions when a release is built.

1.21.0 - 2026-08-27

Changed

• The package now needs SharePoint Framework 1.23.2 or newer.
• The framework dependency accepts any 1.x from 1.23.2 upwards rather than one exact version.
• The package page on npm now explains how to write a widget: the base class, what the context carries, where configuration is stored, and the helpers for debugging against a live installation of Bloom Intranet.

1.20.0 - 2026-08-25

• Added createWidgetDevServerConfig and findAvailablePort, exported from @ichicraft/widgets-widget-base/lib/dev for use in a widget's webpack.dev.ts. The helper resolves a free port before it builds the debug url, so the manifest url handed to the board always matches the port the dev server binds to. This is what allows several widgets to be served and debugged on the same board at the same time.
• Added cssModuleLocalIdentName to the result of createWidgetDevServerConfig. It is keyed by port, so css module class names stay unique between widgets that are served at the same time.
• Added optional debugPort property to WidgetDebugServeConfig, pinning a widget's dev server to a fixed port. When omitted, the first free port from 8080 upwards is used.
• Added optional openBrowser property to WidgetDebugServeConfig. Set it to false for the second and further widgets in a multi-widget debug session, so they serve their bundle without opening a browser window of their own.
• Added webpack and webpack-dev-server as optional peer dependencies. They are only needed when using the lib/dev helpers, which every widget project already has installed.
• Breaking: removed the DebugComponentType enum and the debugComponentType property of WidgetDebugServeConfig. Opening the board on one specific component no longer makes sense now that several widgets can be debugged at once. Remove both from your config/serve.config.ts.

1.19.0 - 2026-08-18

• Added optional bloomGroups provider to WidgetContext, exposing a fetchGroups() function that supplies the tenant's Bloom Group definitions. Widgets can pass it through to their people pickers so Bloom Groups can be offered as suggestions.

1.18.0 - 2026-08-17

• Added optional assetsBaseUrl property to the WidgetContext interface, containing the base URL of the folder the widget bundle was loaded from. This allows widgets to fetch files that are published alongside their bundle, such as per-language translation files.

1.17.0 - 2026-07-16

• Moved UserHelper, ICPersona, ICPersonaType, ICSite, ICTeam and ICTerm to an internal package.

1.16.6 - 2026-06-03

• Replaced unused design.header.activeTextColor with design.header.subTextColor

1.16.5 - 2026-06-01

• Added BuddyRenderOptions interface, passed by the host to BaseWidget.renderBuddy to describe the slot the widget is about to render into.
• Added optional options parameter to BaseWidget.renderBuddy, of type BuddyRenderOptions. Contains an allowRichRendering boolean that signals whether the slot has room for richer rendering than the standard buddy icon button — letting the widget decide synchronously between custom and default rendering.

1.16.4 - 2026-05-27

• Added header property to WidgetDesignContext interface, exposing the header's textColor, iconColor, activeTextColor and activeIconColor from the user's theme.
• Deprecated defaultColor property on WidgetBuddyContext interface in favor of design.header.iconColor (and design.header.activeIconColor for the hover/active state).

1.16.3 - 2026-05-08

• Added whatsNewUrl property to WidgetManifestConfig to allow quick access to updates that the widget has received.
• Added aboutUrl property to WidgetManifestConfig to allow quick access to more information about the widget.

1.16.2 - 2026-03-25

• Fixed issue with using internal library @ic/caching by publishing caching library as public (@ichicraft/caching)

1.16.1 - 2026-03-19

• Addition of notificationBadgeCount property to CommandBarItemProps to allow for a number to be displayed in the badge

1.16.0 - 2026-03-09

• Addition of cache property to instance, variant and manifest level of WidgetContext to centralize cache handling and functionality

1.15.4 - 2026-01-07

• Override version of deep dependency 'validator' to get rid of potential vulnerability

1.15.3 - 2025-12-09

• Added property isIndeterminate to ICTerm interface, used to represent a term's indeterminate checkmark state.

1.15.2 - 2025-11-21

• Added new interface ICTerm, used to represent a SharePoint Taxonomy Term object in code

1.15.1 - 2025-09-30

• Added new interface ICTeam, used to represent a Microsoft Teams team object in code

1.15.0 - 2025-09-29

• Deprecated msGraphClientFactory in favor of msGraphClient in the WidgetManifestConfig interface.

1.14.7 - 2025-08-21

• Added parentId property to the WidgetInstanceContext interface, to support checking the ID of the parent of a widget instance.

1.14.6 - 2025-08-11

• Added updateInstanceConfiguration property to the WidgetInstanceContext interface, to support updating the instance configuration directly in a widget, instead of through the settings panel.

1.14.5 - 2025-08-07

• Added imageUrl property to the CommandBarTab interface, to support displaying images in widget header tabs.

1.14.4 - 2025-08-01

• Added releaseType property to the WidgetManifestConfig interface, to indicate the current stage of the release lifecycle a widget is in.
• Added registerOnBuddyClick property to the WidgetBuddyContext interface, to allow overriding default onClick behavior when clicking on a buddy (by default, it opens the widget in a Callout).

1.14.3 - 2025-07-04

• Added justification string property to widget manifest to describe the reasoning behind the need for certain API permisisons

1.14.2 - 2025-07-02

• Reverted @microsoft/sp-http dependency back to SPFx version 1.18.2 due to postponed upgrade
• Added isOptional boolean to widget manifest to allow marking certain API permission requests as optional

1.14.1 - 2025-06-17

• Reverted module type 'commonjs' for backwards compatibility

1.14.0 - 2025-05-21

• Version bumped @microsoft/sp-http dependency to latest SPFx version 1.21.1

1.13.2 - 2025-04-11

• Minor update in documentation of WebApiPermissionRequest interface

1.13.1 - 2025-03-11

• Added new interface ICSite, used to represent a SharePoint site object in code

1.13.0 - 2025-02-17

• Fixed an issue with detecting external users in UserHelper
• Changed target JavaScript version to ES6

1.12.0 - 2025-02-11

• Added ColorOption interface.
• Added WidgetDesignContext interface.
• Added design property of type WidgetDesignContext to WidgetContext interface, to support UI settings within widgets.
• Deprecated elementBorderRadius property which is renamed to borderRadius and moved under design property in WidgetContext interface.

1.11.6 - 2025-01-30

• Added spServiceScope property to WidgetContext interface.
• Added loadComponentById function to WidgetContext interface.
• Deprecated definition property which is replaced by variant property in WidgetContext interface.
• Deprecated instance.publishNotification function in WidgetContext interface because feature is no longer available.

1.11.5 - 2025-01-21

• Added defaultColor property to WidgetBuddyContext interface.

1.11.4 - 2024-11-08

• Added driveId property to FilePickerFileProps interface.

1.11.3 - 2024-11-05

• Added fileName property to FilePickerFileProps interface.

1.11.2 - 2024-10-21

• Added optional objectId property to the ICPersona interface.

1.11.1 - 2024-10-17

• Made buddy property of type WidgetBuddyContext optional.

1.11.0 - 2024-10-17

• Added renderBuddy function to the BaseWidget class, to support rendering widgets as a buddy.
• Added buddy property of type WidgetBuddyContext to the WidgetContext interface, to support utility functions specifically for a widget buddy.
• Added setBadgeProperties function to the WidgetBuddyContext interface, to allow rendering a badge on top of the buddy.

1.10.8 - 2024-10-15

• Added buddybar to the BoardType type, to support widgets that run in the scope of the upcoming buddy bar feature

1.10.7 - 2024-08-20

• Replaced onInit function with a new asynchronous init function in the BaseWidget class, to allow waiting until initialization is complete.

1.10.6 - 2024-08-19

• Added userDisplayName property to the WidgetContext interface, to allow using the currently signed-in user's display name in widgets.

1.10.5 - 2024-08-07

• Added onSearch property to the CommandBarSearchItem interface, to allow executing a callback when the user presses enter in the search box.

1.10.4 - 2024-07-23

• Added SearchBar value to the CommandBarItemType enum, to allow rendering a command bar item as a search bar.
• Added CommandBarSearchItem interface, to allow passing extra search-related props to a CommandBarItem of type SearchBar.
• Added optional overflowButtonIconName and overflowButtonTooltip properties to the CommandBarTabOptions interface, to allow customization of the overflow menu button.
• Added optional itemCount property to the CommandBarTab interface.
• Added summaries to functions and interfaces related to widget command bar tabs.

1.10.3 - 2024-07-22

• Added override in package.json to use version 2.3.7 instead of 2.3.6 of requirejs because the latter has vulnerability CVE-2024-38999

1.10.2 - 2024-07-19

• Added registerTabs function to the WidgetInstanceContext interface, to allow rendering of tabs in the widget header.
• Added setSelectedTab function to the WidgetInstanceContext interface, to allow setting the current selected tab in the widget header.
• Added CommandBarTab interface.
• Added CommandBarTabOptions interface.

1.10.1 - 2024-07-08

• Added widget-administrator role to the UserRole type.

1.10.0 - 2024-06-25

• Added optional updateDataAccess() function to the BaseWidget class, used to update access to widget-specific data.
• Added administrators property to the WidgetVariantContext interface.

1.9.14 - 2024-06-18

• Change import of SPFI type to decrease bundle sizes in widgets.

1.9.13 - 2024-06-18

• Added spHttpClient property to WidgetContext interface, to perform REST calls against SharePoint.
• Added spHttpClientConfiguration property to WidgetContext interface.

1.9.12 - 2024-06-17

• Added sp property to WidgetContext interface, to allow using a centralized PnPjs version across all widgets.
• Added siteId property to WidgetContext interface.
• Added boardsInstanceId property to WidgetContext interface.

1.9.11 - 2024-06-14

• Fixed handling of null ICPersonaType values in isCurrentUserInScope function of UserHelper class.

1.9.10 - 2024-06-04

• Renamed CustomCommandBarItemProps interface to CommandBarItemProps.
• Merged CommandBarIcon, CommandBarLink and CommandBarItemBase interfaces into the CommandBarItemProps interface, to simplify adding custom command bar items.
• Added Overflow type to CommandBarItemType enum, to allow rendering an item inside the overflow menu.
• Added highlighted property to the CommandBarItemProps interface, to allow rendering an item as if it is being hovered.
• Added cursor property to the CommandBarItemProps interface, to allow a different cursor when hovering over an item.
• Added disabled property to the CommandBarItemProps interface, to allow rendering an item in a disabled state.

1.9.9 - 2024-05-14

• Changed return type of createDeepLink function of the WidgetInstanceContext interface from void to string.

1.9.8 - 2024-05-13

• Added createDeepLink property to the WidgetInstanceContext interface, to allow creating a deep link URL based on the current board and a widget instance.
• Added setDeepLinkData property to the WidgetInstanceContext interface, to allow setting deep link data related to a widget instance in the URL of the current page.
• Added getDeepLinkData property to the WidgetInstanceContext interface, to allow getting deep link data related to a widget instance from the URL of the current page.

1.9.7 - 2024-04-19

• Added hideSpHubNav property to the IFrameDialogOptions interface, to allow hiding the Hub navigation on SharePoint sites.
• Added hideSpSiteHeader property to the IFrameDialogOptions interface, to allow hiding the site header on SharePoint sites.
• Added showHistoryButtons property to the IFrameDialogOptions interface, to render back and forward buttons, allowing the user to navigate the browser history.
• Added showOpenInNewWindow property to the IFrameDialogOptions interface, to render an 'open in new window' button, allowing the user to open the iframe url in a new browser window.

1.9.6 - 2024-04-19

• Changed onRenderHeaderIcon property of the IFrameDialogOptions interface, to work similarly to the widget render functions.

1.9.5 - 2024-04-18

• Added title property to the IFrameDialogOptions interface, to allow rendering a title in the dialog header.
• Added titleUrl property to the IFrameDialogOptions interface, to allow making the dialog header title clickable.
• Added onRenderHeaderIcon property to the IFrameDialogOptions interface, to allow rendering an icon in the dialog header.
• Added onLoad property to the IFrameDialogOptions interface, to support executing some code after the iframe finishes loading.

1.9.4 - 2024-04-11

• Reintroduced the following types: AadHttpClient,AadHttpClientConfiguration,AadHttpClientFactory,AadHttpClientResponse, AadTokenProvider, AadTokenProviderFactory

1.9.2 - 2024-03-21

• Added CommandBarIcon interface, to allow rendering a CustomCommandBarItem as a single icon or an icon button.
• Added CommandBarLink interface, to allow rendering a CustomCommandBarItem as a clickable link.
• Added CommandBarItemBase interface, to act as a base for different types of CustomCommandBarItem.
• Added elementBorderRadius property to the WidgetContext interface, to allow styling widgets according to the configured design preferences.
• Changed CustomCommandBarItemProps type to accept either a CommandBarIcon or a CommandBarLink.

1.9.1 - 2023-10-20

• Added WidgetInstanceContext interface, to allow typing the instance property of the WidgetContext interface.
• Added WidgetVariantContext interface, to allow typing the definition property of the WidgetContext interface.
• Added WidgetManifestContext interface, to allow typing the manifest property of the WidgetContext interface.

1.9.0 - 2023-10-20

• Added optional importData() function to the BaseWidget class, used to import widget-specific data.
• Added optional exportData() function to the BaseWidget class, used to export widget-specific data.
• Added new exported ExportData type.

1.8.17 - 2023-10-09

• Added iconName property to the definition object of the WidgetContext interface, to support using an icon to represent a widget.

1.8.16 - 2023-09-26

• Added Custom value to ICPersonaType enum, to support a custom ICPersona.

1.8.15 - 2023-09-01

• Added thumbnailUrl property to WidgetManifestConfig interface, as a non-translatable substitute of the newly deprecated preview_small property from WidgetImages interface.
• Removed the deprecated preview_small property from WidgetImages interface.

1.8.14 - 2023-09-01

• Added iconName property to WidgetManifestConfig interface, to support using an icon to represent a widget, e.g. in the widget library or widget header.
• Removed the deprecated notificationIcon property from WidgetManifestConfig interface.

1.8.13 - 2023-06-08

• Removed the deprecated resolved property from ICPersona interface

1.8.12 - 2023-04-04

• Changed openFilePicker function to return more details of the picked file in the shape of FilePickerFileProps

1.8.11 - 2023-04-03

• Changed openFilePicker function to return more details of the picked file in the shape of FilePickerFileProps

1.8.10 - 2023-03-30

• Changed openFilePicker function to accept options, to support configuration of picker behavior

1.8.9 - 2023-03-06

• Added registerCustomCommandBarItems function to the instance object of the WidgetContext interface, to support multiple custom buttons in the widget header.
• Added unregisterCustomCommandBarItems function to the instance object of the WidgetContext interface, to support removing all custom buttons in the widget header.
• Added optional id property to exported CustomCommandBarItemProps type, to support removing a custom command bar item by id.
• Added optional pinned property to exported CustomCommandBarItemProps type, to support forcing the widget header to always be visible.
• Added optional showNotificationBadge property to exported CustomCommandBarItemProps type, to support showing a red notification badge over the custom command bar item.
• Added optional order property to exported CustomCommandBarItemProps type, to support changing the order of custom command bar items.
• Changed unregisterCustomCommandBarItem function of the instance object of the WidgetContext interface, to support removing a custom command bar item by id.

1.8.8 - 2023-02-16

• Removed all SharePoint and Teams dependencies.

1.8.7 - 2022-12-13

• Added userRoles property to the WidgetContext interface, to inform widgets of the roles of the current user.
• Added new exported UserRole type.

1.8.6 - 2022-12-08

• Added boardType property to the instance object of the WidgetContext interface, to inform widgets of the type of their board.
• Added allowedBoardTypes property to the definition object of the WidgetContext interface, to inform widget variants of the types of boards it is allowed to be added to.
• Added new exported BoardType type.

1.8.5 - 2022-09-30

• Added setWidgetTitleSuffix() function to the instance object of the WidgetContext interface, to support appending the title of the widget with additional text.
• Added setWidgetSubtitle() function to the instance object of the WidgetContext interface, to support overriding the subtitle of the widget.
• Added setUserConfigButtonVisibilty() function to the instance object of the WidgetContext interface, to support hiding the settings button from the widget header.
• Fixed spelling of setWidgetHeaderVisibilty() function. The function is now called setWidgetHeaderVisibility().

1.8.4 - 2022-09-05

• Added openIFrameDialog() function to the WidgetContext interface. This has the same functionality as the openUrlInDialog() function of the instance object, but adds more control over the dimensions of the dialog. The function openUrlInDialog() is now deprecated.

1.8.3 - 2022-08-16

• Added openFilePicker() function to the WidgetContext interface to support file selection from within a widget.

1.8.2 - 2022-07-06

• Added subtitle property to the WidgetResource interface.

1.8.1 - 2022-06-17

• Added new section analytics to WidgetManifestConfig interface to allow definition of time-based events that can be raised by a widget.
• Added raiseEvent(...) to the instance object of the WidgetContent interface, allowing widgets to raise an event.

1.7.11 - 2022-03-23

• Added setWidgetHeaderVisibilty() function to the instance object of the WidgetContext interface, allowing widgets to render in full height.

1.7.9 - 2022-01-20

• Added userAccountCreated date/time to the WidgetContext interface.

1.7.8 - 2022-01-18

Changed

• Added initiateWidgetDeletion() function to the WidgetContext interface.

1.7.7 - 2022-01-14

Changed

• Added tenantId property to the WidgetContext interface.

1.7.6 - 2021-11-04

Changed

• Added theme property to the WidgetContext interface to give access to currently applied theme.

1.7.5 - 2021-10-26

Changed

• Added userSecurityGroups and userSharePointGroups properties to the WidgetContext interface to inform widgets of SharePoint and security group memberships of the current user.

1.7.4 - 2021-10-20

Changed

• Added contentLanguages property to the WidgetContext interface to inform widgets of the available content languages as configured in Ichicraft Boards.

1.7.3 - 2021-10-04

Changed

• Added manifestVersion property to the WidgetManifestConfig interface to support multiple versions of the manifest. Current version is 2 which introduced this and the externals property.
• Added externals property to the WidgetManifestConfig interface to support libraries that can be loaded separately from the widget bundle. This reduces widget bundle size and improves overal performance of Ichicraft Boards.

1.6.1 - 2021-02-18

Changed

• Added userEmail property to the WidgetContext interface to provide current user's email address to widgets.

1.5.0 - 2021-02-16

Changed

• Added teamsSdk property to the WidgetContext interface to allow interaction with Teams in case widget board is running in Teams client. Will be undefined if running in SharePoint.

1.4.0 - 2021-01-25

Changed

• Added several properties to the WidgetContext interface to identify the context in which the widget is shown (e.g. Team Browser hosted)

1.3.0 - 2021-01-15

Changed

• registerCustomCommandBarItem() is added to the WidgetContext interface as a function to call from within a widget instance to render an additional command bar item in the widget header.
• unregisterCustomCommandBarItem() is added to the WidgetContext interface as a function to call from within a widget instance to remove a previously added command bar item from the widget header.

1.2.0 - 2021-01-15

Changed

• loadScript() is added to the WidgetContext interface as a function to call from within a widget in case an external script needs to be loaded. This allows the widget board to load external javascript.

1.1.0 - 2021-01-11

Changed

• handleFatalError() is added to the WidgetContext interface as a function to call from within a widget in case of an unhandled/unresolvable error. This allows the widget board to handle this situation gracefully.
• deps: removed dependency ajv

<= 1.0.5 - 2020-12-07

No changelog was maintained for the earlier versions.