Create custom widgets for the Azure API Management Developer Portal

6 min readOct 27, 2023

Azure API Management features a developer portal that contains a visual editor and built-in widgets so that you can customize and style the portal’s appearance. However, you may need to customize the portal further with custom functionality. This article explains how to add custom React widgets to your Azure API Management developer portal using the React Component Toolkit.

React Component Toolkit

The React Component Toolkit is a toolkit for building and testing react components and includes a set of unique features including AI component generation and automatic conversion to Azure APIM Widgets.

Features

Can create a new basic react component (or you can use Azure Open AI and create a basis for a new one)
Can convert a react component into an Azure API Management Widget
Integrates with Azure Open AI allowing the creation of components from a description alone
Can be tested standalone using ladle, which is built into the toolkit stack
Unit and code coverage testing through Jest (including snapshot testing)
Uses css as code through Styled Components out of the box
Automatically adds dependencies for created components
Includes rollup for packaging components

Install React Component Toolkit

There are two ways to install the React Component Toolkit:

Install via azdev
Manual install

Install React Component Toolkit via azdev

Use the Official Azure Samples GitHub instructions to install and configure the React Component Toolkit via azdev: Azure Samples — react-component-toolkit (Getting Started)

Important: Installing via azdev includes deploying Azure OpenAI and Azure APIM into your Azure subscription. The regions that currently support the models used in this sample are East US, South Central US, or West Europe

Install React Component Toolkit manually

Install the latest release of Node.js
Clone the React Component Toolkit repository
Fill in your values into .env.empty and rename the file to .env
In the root directory, run the command node install.mjs

Important: Installing manually requires a .env file to be configured to enable Azure Open AI and APIM widget functionality. An example .env.empty file is included in the root directory for you to fill out with your environment values (Without quotes). When you have filled out the values, copy/rename the file to .env.
- The following values are in your environment file (if you don’t plan to use Azure OpenAI, you may leave those values blank):
APIM_OPENURL - APIM developer portal URL for widget development and testing (e.g. https://contoso.developer.azure-api.net/)
APIM_RESOURCEID - The Azure Tenant ID ofch (Fill this in if you use cross-tenant AD authentication) Azure API Management resource ID (e.g. subscriptions/<subscription-id/resourceGroups/<resource-group-name/providers/Microsoft.ApiManagement/service/<api-management service-name).
APIM_TENANTID - Azure API Management resource ID (e.g. subscriptions/<subscription-id/resourceGroups/<resource-group-name/providers/Microsoft.ApiManagement/service/<api-management service-name). (Note: Set this field if you are in a multi-tenant organization or get the following error “Error: Could not get storage SAS URL” when deploying a widget to the portal)
AOI_ENDPOINT - Azure OpenAI Endpoint (e.g. https://contoso.openai.azure.com/).
AOI_APIKEY - Azure OpenAI API Key.
AOI_DEPLOYMENT - Azure OpenAI Model Deployment Name (e.g. contoso-deployment).
AOI_ENABLED - Set to true if you plan generate components using Azure OpenAI.
DEBUG_DIR - The path where the prompt and the response from Azure OpenAI will be stored. The path is OS specific (e.g. Windows: C:\Users\contoso\Desktop\Debug | Linux/Mac: home\user\contoso\debug).

Remember to run the command node install.mjs in the root directory as stated in step 4 above.

Use React Component Toolkit

After you have installed the React Component Toolkit, it’s time to create and deploy a custom react widget. In this section we’ll go over the following items:

Create and unit test a custom widget
Test a custom widget in the developer portal
Deploy a custom widget to the developer portal

Create and unit test a custom widget

Open your terminal to the root directory
Run the following command npm run createtemplate [component_name], replacing [component_name] with the name of your widget, to create a new react component template with stories and unit tests

Note: Run the following command npm run createnew [component_description], replacing [component_description] with the description of your widget (in quotes), to create an AI generated react component using Azure Open AI (configured via .env) with stories and unit tests

After creating the react component, you can run the following command npm run ladle:dev to get started and see your components running with debugging available

Note: Run the following command npm run ladle:prod to see current components running with a full production build.

Once you have your react component complete and have created unit tests, run the following command npm run test (or npm test) to run all component unit tests

Important: If you get a snapshot failed error, run the following command npm run test:update to update all snapshots for unit tests.

Done! You have successfully created a react component using the React Component Toolkit. Move on to the next section to learn how to deploy your react component as a custom widget in the developer portal.

Tip: Run the following command npm run removecomponent [component_name], replacing [component_name] with the name of your widget, to delete the react component and associated stories and unit tests.

Test a custom widget in the developer portal

Open your terminal to the root directory
Run the following command npm run packagewidget [existing_component_name], replacing [existing_component_name] with the name of your component, to package your component as a custom widget for the Azure API Management Developer Portal
Run the following command npm run hostwidget [existing_component_name], replacing [existing_component_name] with the name of your component, to test a widget locally in development mode of the Azure API Management Developer Portal
After the command is finished, your custom widget will be running in development mode of the developer portal. Using the portal’s administrative interface, you can add it on pages in the developer portal and set values for any custom properties configured in the widget

Note: If you don’t see the custom widget in your developer portal, append /?MS_APIM_CW_localhost_port=3000 to the developer portal URL. Change the port number if your React Component Toolkit runs on a different port.

Deploy a custom widget to the developer portal

Open your terminal to the root directory
Run the following command npm run packagewidget [existing_component_name], replacing [existing_component_name] with the name of your component, to package your component as a custom widget for the Azure API Management Developer Portal
Run the following command npm run deploywidget [existing_component_name], replacing [existing_component_name] with the name of your component, to deploy a widget to the Azure API Management Developer Portal
After the command is finished, your custom widget will be deployed to your developer portal. Using the portal’s administrative interface, you can add it on pages in the developer portal and set values for any custom properties configured in the widget

To see your deployed custom widget in production in the Azure API Management Developer Portal, you will need to publish the developer portal. You can see how to do that here: Tutorial — Access and customize the developer portal — Azure API Management | Microsoft Learn

Note: If you deploy an updated custom widget at a later date, the widget used in production won’t update until you republish the developer portal.

React Component Toolkit Commands

npm run ladle:dev - to get started and see current component running with debugging available
npm run ladle:prod - to get started and see current components running with a full production build
npm run cleanup - to clear dist, build_artifacts and unit test coverage results
npm run rollup - runs rollup -c
npm run build - runs npm cleanup followed by npm rollup
npm run createnew [component_description] - create an AI generated component using Azure Open AI (configured via .env) with stories and unit tests
npm run createtemplate [component_name] - to create a new ready to run component template with stories and unit tests
npm run removecomponent [component_name] - to delete a component and associated stories and unit tests
npm run packagewidget [existing_component_name] - to package a component as a widget ready for the Azure API Management Developer Portal
npm run hostwidget [existing_component_name] - to test a packaged widget locally in development mode of the Azure API Management Developer Portal
npm run deploywidget [existing_component_name] - to deploy a packaged widget to the Azure API Management Developer Portal
npm run test (or npm test) - to run all component unit tests (src/unittests)
npm run test:update - to update all snapshots for unit tests
npm run test:watch - to run jest in watch mode

Next steps

Learn more about the developer portal and the React Component Toolkit:

Reach out to me or leave a response below if you run into any issues or something is unclear. Happy Coding and God Bless!