create-dynamics-app

Unified CLI to scaffold Dynamics 365 / Power Platform artifacts — one tool, per-artifact templates, a Fluent v8/v9 choice, integrated dev-tools, and an optional from-design mode.

create-dynamics-app <project-name> --artifact <id> [--v8|--v9]

Quick start

Prerequisite: Node 20+ (engines.node >= 20). Every package is public on npm — no login, no auth, no private registry.

Scaffold a Dynamics custom page and run it (the scaffold step runs npm install for you):

npx @khester/create-dynamics-app my-custom-page --artifact react-custom-page --v8
cd my-custom-page
npm run dev      # webpack dev server + mock Xrm — open in the browser
npm run build    # production bundle → dist/ (deployable web resource)

• Run with no flags (npx @khester/create-dynamics-app my-custom-page) for an interactive picker.
• Use --v9 for Fluent UI v9 (default is v8 — the safe choice for Power Pages / Dynamics).
• Add --with-components to also install the @khester/reusable-components Fluent v8 set (see Flags).
• Pin a version (@khester/[email protected]) for reproducible builds.

Connect to a live Dataverse org (optional)

The scaffold ships dev-tools that pull real metadata. Needs the Azure CLI (az login into the tenant) or DYNAMICS_* env vars:

npm run auth:token                                   # az → token written to .env (git-ignored)
npm run metadata:pull -- --entities account,contact  # live metadata → typed src/constants + src/models

Artifacts (--artifact)

| id | What it scaffolds | Fluent | |----|-------------------|--------| | react-custom-page | React SPA for a model-driven custom page | v8 | | power-pages | Power Pages portal starter | v8 | | pcf-field | PCF field control (property-type aware: text/number/boolean/date) | v8 | | pcf-dataset | PCF dataset/grid control (DetailsList) | v8 | | grid-customizer | Editable-grid cell-renderer customizer | v9 | | web-resource | React web resource (webpack bundle) | v8 or v9 | | dialog-form | Single React form host (opened as a dialog) | v8 or v9 | | static-web-app | Azure SWA — React frontend + Functions api/ | v8 or v9 | | teams-app | Teams tab (React + teams-js), optional Graph (--graph) | v9 |

Run with no flags for an interactive picker.

Flags

• -a, --artifact <id> — artifact to scaffold (see table).
• --v8 / --v9 (or -l, --library fluent-v8|fluent-v9) — Fluent version for artifacts that support a choice. Only the chosen library is installed.
• -n, --namespace, --component-name, --property-type — PCF options.
• --graph — include Microsoft Graph (teams-app).
• --with-components — install @khester/reusable-components (a curated Fluent v8 React set: ReusableCard, CustomSection, FileUploadField, SearchComponent, DetailsListComponent, the localhost-gated logger, …) plus its @fluentui/react v8 peer. Honored for the v8 React hosts — react-custom-page, power-pages, web-resource, dialog-form; warned-and-ignored elsewhere; errors if combined with --v9.
• --from-design <file> — generate from a form-builder export (a FormBuilderProject JSON, e.g. from /generate-form). Wraps @dataverse-kit/export-engine to produce a deployable project (host + form code + a design-derived data layer). Supported targets: web-resource, pcf, static-web-app. From-design output is generated by the export engine and is structurally different from a blank starter (it ships its own token tooling); package.json.dynamicsKit.artifact records which.
• --skip-git, --skip-install.

Dev-tools (in generated projects)

Blank starters get package.json scripts for: auth:token (Azure CLI → .env), metadata:pull (typed entities via dvgen), smoke:live (live-org retrieve), plus a mock-Xrm helper for local serve.

Breaking changes in 2.0.0

See CHANGELOG.md. In short: removed the consulting flags (-c/-e/-p/-d/--generate-sample); --template dynamics-365|pcf-control are removed (use --artifact react-custom-page / --artifact pcf-field); --template power-pages still works as a deprecated alias.

Testing & coverage boundaries

• Unit + smoke tests (npm test) run the scaffold pipeline for all 9 artifacts (zero-residual-token + variant/prune checks) but do not npm install or build the generated projects.
• React artifacts are verified to tsc --noEmit clean for v8 and v9 via manual installs; PCF type-correctness (against generated ManifestTypes from pcf-scripts refreshTypes) is verified manually, not in CI.
• The --from-design generated-project build is verified manually.