Skip to main content

Extension Template Catalog

Overview​

The extension template catalog is a remote, versioned list of Candescent-maintained starters for mobile widgets and features. Use it when you want a DI-backed, vetted project layout instead of a blank offline scaffold — the generator downloads the latest catalog, lets you pick a template interactively, and produces a runnable Nx project wired for @cdx-extensions/di-sdk (PlatformSDK) and the mobile sandbox.

Run all commands below from your FI repository root.

Browse the Catalog​

The catalog is not enumerated in this guide — it expands over time. Discover the current set at generation time (interactive prompts) or with the list commands below.

Setup​

Install the generator and configure the @cdx-extensions registry so template overlay packages can be downloaded:

Bash
npm install @cdx-extensions/extension-generator-mobile
# .npmrc
@cdx-extensions:registry=https://registry.npmjs.org/

See what's available​

Bash
nx run list-mobile-templates
nx run list-mobile-widget-templates
nx run list-mobile-feature-templates

These commands fetch the same remote catalog the generators use and print entries grouped by type and category.

Example: Investment Portfolio (Data Chart)​

Browse — category and template picker:

$ nx run generate-mobile-widget

? Choose a template category: › Data-chart
? Choose a template: › Investment Portfolio — Financial widget with donut chart, portfolio legend, and SDK branding hooks.
? Enter your FI Id (digits only, e.g. 0123): › 0123
? Choose a name for your widget (kebab-case, e.g. acme-portfolio): › acme-portfolio

Outcome — generated widget in the mobile sandbox:

Investment Portfolio widget with donut chart and legend in the mobile sandbox

Example: Agent Chat (Interactive)​

Browse — category and template picker:

$ nx run generate-mobile-feature

? Choose a template category: › Interactive
? Choose a template: › Agent Chat — Bring-your-own-agent full-screen chat feature.
? Enter your FI Id (digits only, e.g. 0123): › 0123
? Choose a name for your feature (kebab-case, e.g. agent-chat): › acme-chat

Outcome — generated feature in the mobile sandbox:

Agent Chat feature with chat UI in the mobile sandbox
note

Template ids, categories, and counts change as Candescent publishes new starters. Always use nx run list-mobile-templates (or the interactive generator) for the authoritative list — not this guide.

Generate Your Extension​

Interactive (full flow)​

Bash
nx run generate-mobile-extensions

Equivalent:

Bash
nx g @cdx-extensions/extension-generator-mobile:generate

Flow:

  1. Fetches the latest catalog from the remote URL (with cache and local fallbacks)
  2. Prompts you to pick an extension type (widget or feature)
  3. Lists templates grouped by category
  4. Prompts you to pick a category, then a template
  5. Prompts for your FI Id and extension name
  6. Optionally prompts for mock API baseUrl and apiPath when the template supports it
  7. Downloads the selected npm template package and scaffolds the project

Widget or feature only​

Skip the type picker when you already know what you are building:

Bash
nx run generate-mobile-widget    # widgets only
nx run generate-mobile-feature   # features only
Workspace commandUnderlying generator
nx run generate-mobile-extensions@cdx-extensions/extension-generator-mobile:generate
nx run generate-mobile-widget@cdx-extensions/extension-generator-mobile:widget
nx run generate-mobile-feature@cdx-extensions/extension-generator-mobile:feature

Non-Interactive / CI Usage​

Pass generator options after --:

Bash
nx run generate-mobile-widget -- --template=investment-portfolio --fiId=0123 --name=acme-portfolio
nx run generate-mobile-feature -- --template=agent-chat --fiId=0123 --name=acme-chat
OptionRequiredDescription
fiIdYesNumeric FI id — digits only (0-9); accepts 4 or 5 digits (e.g. 0123, 03100). Values shorter than 4 digits are zero-padded (123 → 0123).
nameYesExtension slug in kebab-case
templateYesCatalog template id (discover ids with nx run list-mobile-templates) or full npm package name
noCacheNoRe-download catalog and template overlays (skip ~/.cdx/cache)
catalogUrlNoOverride remote catalog URL
directoryNoOutput parent (widgets/mobile or features/mobile)
sandboxPathNoSandbox auto-wiring (default playground/mobile-sandbox)
baseUrlNoMock API origin (widgets with config.ts.tmpl only)
apiPathNoMock API path (widgets with config.ts.tmpl only)
skipApiValidationNoSkip live HTTP validation during generation

What You Get​

In addition to extension source from the selected template package, the generator writes CDX project scaffold files:

  • package.json, project.json, tsconfig.json
  • src/index.ts, component entry file, and branding types

Output paths:

  • Widgets → widgets/mobile/<name>/
  • Features → features/mobile/<name>/

The generator also auto-wires the new project into playground/mobile-sandbox so you can preview immediately.

Only modify files inside src/ for your extension logic and UI. See Getting Started for the full editability guide.

Advanced​

Catalog source and cache​

On each run the generator syncs catalog/extension-templates.json using this order:

  1. Remote — https://raw.githubusercontent.com/candescent-dev/cdx-extensibility-apps/main/catalog/extension-templates.json
  2. Cache — ~/.cdx/cache/catalog/ when the remote fetch fails
  3. Local workspace — catalog/extension-templates.json in your repo when both remote and cache are unavailable

Override with CDX_EXTENSION_CATALOG_URL or --catalogUrl. The catalog is cached for approximately 5 minutes; use --noCache after a platform publish.

note

The URL above is the target public mirror. The generator package may still ship a temporary default until that mirror is promoted — verify the default in your installed @cdx-extensions/extension-generator-mobile package or set CDX_EXTENSION_CATALOG_URL explicitly.

Template packages are cached under ~/.cdx/cache/<package>@<version>/dist/.

Mock API URL (config.ts templates)​

Templates that ship config.ts.tmpl with baseUrl and apiPath trigger a mock API flow during generation. The generator reads defaults from that file, optionally validates the response when mockApiContract is set, and patches the generated widget's src/config.ts.

Features without config.ts.tmpl skip URL prompts entirely.

Supported mockApiContract values: portfolio-allocation, credit-score.

Bash
nx run generate-mobile-widget -- \
  --template=investment-portfolio --fiId=0123 --name=acme-portfolio \
  --baseUrl=https://candescent.wiremockapi.cloud \
  --apiPath=/investment-portfolio

nx run generate-mobile-widget -- \
  --template=investment-portfolio --fiId=0123 --name=acme-portfolio \
  --skipApiValidation

Next Steps​