Widget Development

This guide covers the full widget development workflow with the CLI: browsing templates, scaffolding a project, previewing in a local playground, and submitting for review.

Templates

The CLI includes 9 widget templates (5 web + 4 mobile) across four categories. Each template scaffolds a fully functional widget with the relevant SDK integrations pre-wired.

Template	Category	Platforms	SDK Features
sdk-demo	Starter	web, mobile	useUserContext, useBranding, getHttpClient
data-chart	Data Display	web, mobile	useUserContext, useBranding, getHttpClient
agent-chat	Interactive	web, mobile	useUserContext, getHttpClient
promotional-card	Promotional	web	useBranding
oidc-auth	Authenticated	web, mobile	useUserContext, useBranding, getHttpClient

Browse templates interactively:

Bash

forge widget templates                   # list all templates grouped by category
forge widget templates --id data-chart   # view details for a specific template

Template Inputs

Some templates collect additional configuration during creation. For example:

• data-chart prompts for an API URL to fetch chart data (defaults to the mock API server if running).
• oidc-auth prompts for OIDC client ID and FI domain (auto-detects the local OIDC Toolkit if running).

Smart defaults are provided for all inputs. Press Enter to accept the default, or type a custom value.

Creating a Widget

Interactive Creation

Run forge widget create without flags for a fully guided experience:

Bash

forge widget create

The CLI prompts for:

1. Widget name (kebab-case)
2. Target platform (Web or Mobile)
3. Template (optional — defaults to sdk-demo)
4. Template-specific inputs (API URLs, OIDC credentials, etc.)

The widget is scaffolded into the Nx monorepo at ~/.forge/cdx-extensibility-apps/samples/<platform>/widgets/<name>-widget/ and is immediately previewable.

Flags for Non-Interactive Usage

Bash

forge widget create my-portfolio --platform web --template data-chart
forge widget create my-chat --platform mobile --template agent-chat

OIDC-Authenticated Widget

The oidc-auth template scaffolds a widget with a complete OIDC authentication flow:

Bash

# Auto-detects local OIDC Toolkit (start with `forge oidc up`)
forge widget create secure-widget --template oidc-auth

# Or provide production credentials
forge widget create secure-widget --template oidc-auth --client-id my-app --fi-domain acmebank

First-Run Auto-Setup

On first use, the CLI auto-clones the cdx-extensibility-apps template to ~/.forge/cdx-extensibility-apps. This provides the Nx workspace, playground configurations, and sample widgets. Subsequent commands reuse this checkout.

Previewing a Widget

Web Preview (OLB Playground)

Bash

forge widget preview my-portfolio

This starts the Nx dev server, launches the OLB Docker playground, and opens the banking shell in your browser. The widget loads via Module Federation into a widget slot.

To run the Nx dev server without the Docker playground:

Bash

forge widget preview my-portfolio --no-playground

Mobile Preview (Expo Sandbox)

Bash

forge widget preview my-portfolio --platform mobile

This starts the Expo mobile sandbox with Metro Bundler.

Preview options (any of):

• Physical device — install Expo Go on iOS or Android, then scan the QR code from inside the Expo Go app. Your phone must be on the same Wi-Fi network as your dev machine.
• iOS Simulator — press i in the Metro terminal (requires Xcode on macOS).
• Android Emulator — press a in the Metro terminal (requires Android Studio).
• Tunnel mode — if your phone cannot reach your dev machine over local Wi-Fi (corporate networks, cellular, etc.), restart Metro with npx expo start --tunnel to route through Expo's servers.

important

Use the Expo Go app's built-in QR scanner to scan the exp:// URL. The iPhone Camera app does not handle exp:// URLs.

Interactive Widget Picker

Running forge widget preview without a widget name presents an interactive picker showing all available widgets across both platforms, with [web] and [mobile] labels and source directory paths:

Bash

forge widget preview

The picker includes a + Create a new widget... option that launches the creation flow and then immediately previews the new widget.

Pre-Flight URL Checks

For web preview, the CLI checks that the OLB playground and the widget's remoteEntry.js are reachable before opening the browser. If either is unavailable, the CLI prints a diagnostic message instead of opening a blank page.

Building a Widget

Create a production build:

Bash

forge widget build my-portfolio                    # default environment
forge widget build my-portfolio --env production   # specific environment

Supported environments: production, stage, qal, development.

Submitting a Widget

Pre-Flight Context

forge widget submit displays your submission context before proceeding:

Submission context
  Environment:  sandbox
  Organization: Acme Bank
  FI ID:        03100
  Repository:   dbk-promotions-sandbox-03100
  User:         developer@acmebank.com

Interactive Submission

Bash

forge widget submit

The CLI prompts for:

1. Widget selection — picker with [web] / [mobile] labels and source paths
2. Platform confirmation — auto-detected from creation metadata
3. Description — free-text summary of the widget

Localhost URL Guardrail

If the widget's manifest contains localhost URLs (from development with the mock API server or OIDC Toolkit), the CLI prompts you to replace each one with a production URL before submission:

⚠ Widget "spend-chart-widget" has local dev URLs that need production values:

  1. apiUrl
     Dev: http://localhost:4010/api/chart-data/spending
✔ Production URL for apiUrl: https://api.acmebank.com/chart-data/spending

Pre-Submit Lint Checks

By default, forge widget submit runs the following before creating the PR:

• ESLint — catches common JavaScript/TypeScript issues
• TypeScript type-check — verifies the widget compiles
• markdownlint — validates the widget's README.md

If a lint error blocks submission, fix and re-run it. To skip the checks (e.g., when debugging metadata issues), use --no-lint:

Bash

forge widget submit my-portfolio --no-lint

Submission Workflow

After confirmation, the CLI:

1. Clones your FI repository from dfh-candescent-extensions.
2. Creates a feature branch (or pushes to the existing branch with -u/--update).
3. Copies the widget source files.
4. Commits and pushes the branch.
5. Creates (or updates) a GitHub PR with structured metadata.

To force a fresh PR even when one is already open for the widget, use --new. To push additional commits to an existing PR, use -u / --update.

Tracking, Publishing, and Deploying

After submission:

Bash

forge submission list                          # list all submissions with status
forge submission dashboard                     # aggregated stats and recent activity
forge submission publish my-portfolio          # merge approved PR + trigger CI deploy
forge submission deploy my-portfolio           # promote the published component to production

Lifecycle: Submit → PR Created → In Review → Approved → Publish (merge PR + CI deploy) → Deploy (production)

Web vs. Mobile Widgets

	Web	Mobile
Scaffold	@cdx-extensions/widget-template-web (Module Federation)	@cdx-extensions/widget-template-mobile (React Native)
Preview	Nx dev server + OLB Docker playground	Expo mobile sandbox
UI Framework	React + MUI	React Native
SDK	@cdx-extensions/di-sdk	@cdx-extensions/di-sdk
Build	Webpack (Module Federation)	Metro Bundler

Platform is recorded in .forge-manifest.json at create/preview time and validated at submit time. Use --force on submit to bypass validation.

Mock API Server

For templates that fetch data from an API (such as data-chart), the CLI integrates with the cdx-mock-data-apis server. If the mock server is running at http://localhost:4010, templates auto-detect it and offer dataset selection during creation.

Start the mock server separately:

Bash

cd cdx-mock-data-apis
pnpm run dev

The mock server provides varied datasets (spending categories, net worth aggregations, investment portfolios) that match the template scenarios.

Next Steps

• Aspect Development — Build and submit JavaScript Aspects
• Command Reference — Full list of widget commands and flags
• Troubleshooting — Common widget development issues