@cdx-extensions/extension-generator-web

Nx plugin for generating catalog-driven web extension widgets from catalog/extension-templates.json.

Part of extensibility-sdk-extension-generator. Separate from the offline starter: @cdx-extensions/widget-template-web.

Install

pnpm add @cdx-extensions/extension-generator-web

Generate

nx g @cdx-extensions/extension-generator-web:widget <widget-name>

Interactive flow:

1. Fetches the latest catalog from GitHub (with cache and local fallbacks)
2. Lists web widget templates by category (e.g. financial)
3. Prompts you to pick a category, then a template
4. Downloads the selected npm template package and scaffolds the widget under widgets/web/<name>-widget/

Skip the template prompt by passing --template (catalog id or npm package name):

nx g @cdx-extensions/extension-generator-web:widget my-widget \
  --template=investment-portfolio

Non-interactive environment URLs

When both --name and --template are provided, the environment prompt is skipped and the widget is created with template defaults.

Optionally set API URLs for one or more environment files via flags (no prompt):

nx g @cdx-extensions/extension-generator-web:widget my-widget \
  --template=investment-portfolio \
  --local="https://api.example.local" \
  --production="https://api.example.com"

| Flag | Environment file | |------|------------------| | --local | environment.ts | | --production | environment.production.ts | | --sandbox | environment.sandbox.ts | | --stage | environment.stage.ts |

Interactive runs (when name or template is omitted) still prompt to pick one environment and enter a URL; that flow is unchanged.

Options

| Option | Default | Description | |--------|---------|-------------| | name | — | Widget slug (required) | | template | — | Catalog template id or npm package (skips interactive picker) | | stackWidget | false | Stack widget layout | | local | — | API URL for environment.ts (non-interactive) | | production | — | API URL for environment.production.ts (non-interactive) | | sandbox | — | API URL for environment.sandbox.ts (non-interactive) | | stage | — | API URL for environment.stage.ts (non-interactive) |

Catalog source

On each run the generator:

1. First tries the remote catalog at
   https://github.com/candescent-dev/cdx-extensibility-apps/blob/main/catalog/extension-templates.json
2. On success — caches it at ~/.cdx/cache/catalog/extension-templates.json
3. On remote failure — uses the cached catalog if present
4. On cache miss — uses the workspace catalog/extension-templates.json if present

Widget prompts read from web.templates in the loaded catalog. No nx.json configuration is required.

Template resolution

For each catalog template package:

1. Read the pinned version from catalog/extension-templates.json (or resolve latest from the registry).
2. If ~/.cdx/cache/<package>@<version>/dist/ already exists, use it.
3. Otherwise run npm pack against the registry in workspace .npmrc (JFrog for @cdx-extensions/*), extract dist/, and cache it for the next run.

When to use which generator

| Need | Generator | |------|-----------| | Quick offline starter | @cdx-extensions/widget-template-web:widget | | Catalog / DI templates | @cdx-extensions/extension-generator-web:widget |

Cache

• Catalog: ~/.cdx/cache/catalog/extension-templates.json
• Template packages: ~/.cdx/cache/<package>@<version>/dist/

Repeat runs reuse cached templates and do not re-download from npm.

Generated project files

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

• .babelrc, .eslintrc.json
• jest.config.ts, webpack.config.ts, module-federation.config.ts
• project.json, tsconfig.json, tsconfig.app.json, tsconfig.spec.json

Scaffold templates ship in this package under dist/projectFiles/. When a published template package includes them under dist/, those versions take precedence.

Utilities

This package also ships monorepo build helpers under src/scripts/ (published as dist/scripts/):

pnpm exec stage-nx-package --projectRoot . --outDir dist --copy src package.json

Build & publish

From this directory:

pnpm install
pnpm run build
pnpm publish --tag dev

The @cdx-extensions registry is configured in .npmrc (JFrog). Only dist/ and package metadata are published, matching @cdx-extensions/widget-template-web.

CI: extension-generator-workflow.yml (JFrog + public npm on main).