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 seven widget scaffolds (four web + three 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

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:

• data-chart — prompts for an API URL to fetch chart data (defaults to the mock API server at http://localhost:4010 when running). During creation the CLI can offer dataset selection from the mock server. Supported mock datasets: investment-portfolio, spending, credit-score, loan-breakdown, savings-goals, net-worth, income-expense.
• agent-chat — prompts for agentEndpoint (default /api/agent/chat). The widget routes chat messages through getHttpClient(); unreachable endpoints fall back to mock responses.

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, etc.)

The widget is scaffolded into the Nx monorepo at ~/.forge/cdx-extensibility-apps/widgets/<platform>/. Web generators often append -widget to the directory name. The widget 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

# Scaffold as plain local files only — no Nx project, no playground
forge widget create my-widget --local
forge widget create my-widget --local --dir ./src/widgets

The --local flag creates widget source files in a plain directory (default ./widgets/) without setting up an Nx project. Local widgets cannot be previewed with forge widget preview and cannot be submitted with forge widget submit. Recreate without --local for playground, Expo preview, or submit.

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. See Web Playground for Docker setup, Aspect Manager, and troubleshooting.

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. Forge targets an iOS Simulator or Android Emulator by default (--mobile-device ios|android) and opens Expo Go there.

Physical-device Expo Go is a fallback after emulator boot fails. Phone and machine must be on the same Wi-Fi. Use Expo Go's built-in QR scanner. The iPhone Camera app does not handle exp:// URLs.

Do not start Expo by hand (npx expo start --tunnel). That skips the widget preview target the CLI sets. Re-run forge widget preview <name> --platform mobile. See Mobile preview.

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                     # production build (default)
forge widget build my-portfolio --env development   # development build

forge widget build defaults to a production build. Pass --env development for a development build.

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), 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

You can configure URLs ahead of time (without waiting for the submit prompt):

Bash

forge widget set-urls
forge widget set-urls my-portfolio

You can also pass a single URL at submit time with --source-url <url> (see Command Reference for more details).

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

TypeScript failures abort the submit. ESLint rule failures abort; a missing ESLint plugin is a warning. Markdownlint warnings do not abort. To skip the checks when debugging metadata, 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.

If a submit pushed your branch but failed to open the GitHub PR, retry PR creation without re-pushing:

Bash

forge widget submit my-portfolio --retry-pr

The CLI uses pendingBranch metadata recorded on the failed run. This flag is mutually exclusive with --update and --new.

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 (offline)	@cdx-extensions/widget-template-web (Module Federation)	@cdx-extensions/widget-template-mobile (React Native)
Scaffold (catalog)	nx run generate-web-widget / nx run generate-web-extensions	npx nx run generate-mobile-widget / generate-mobile-extensions
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 (data-chart, agent-chat), the CLI integrates with the cdx-mock-data-apis server on port 4010. forge widget api-contract is docs-only. It does not start the mock. forge widget preview starts the mock only when the widget source references the local :4010 API. On first use the CLI clones the mock repo into ~/.forge/cdx-mock/ and installs its dependencies.

If auto-start fails or you want the server running continuously in a separate terminal, start it from the CLI-managed path:

Bash

cd ~/.forge/cdx-mock/cdx-mock-data-apis
pnpm run dev

API contracts

To view the response shapes and curl examples that your backend must implement (or what the mock server provides locally):

Bash

forge widget api-contract data-chart
forge widget api-contract data-chart --dataset spending
forge widget api-contract agent-chat
forge widget api-contract data-chart --format openapi --copy

Chart datasets: investment-portfolio, spending, credit-score, loan-breakdown, savings-goals, net-worth, income-expense.

Next Steps

• Web Playground — OLB Docker shell, Aspect Manager, and local preview setup
• Aspect Development — Build and submit JavaScript Aspects
• Command Reference — Full list of widget commands and flags
• Troubleshooting — Common widget development issues