PCF Components in the Field

The one true starting point — wires manifest, tsconfig, and build together.

pac pcf init --namespace {{namespace}} --name {{component_name}} --template {{template}} --run-npm-install

Prerequisites:

pac CLI installed; empty target folder

Run from:

The new component's (empty) folder

Expected output:

Scaffold files created, npm install completes

Success looks like:

ControlManifest.Input.xml exists and npm run build succeeds

Follows Rule 1

Instant render loop — the whole dev cycle lives here.

npm start watch

Prerequisites:

npm install completed

Run from:

Component root (where package.json lives)

Expected output:

Browser opens the harness at localhost:8181 with live reload

Success looks like:

Component renders and re-renders when you edit source

Follows Rule 4

The fast inner loop against a real Dataverse — dev environments only.

pac pcf push --publisher-prefix {{publisher_prefix}}

Careful: Creates/updates a temporary unmanaged dev solution — never aim this at a shared or downstream environment.

Prerequisites:

pac auth create already pointed at your DEV environment

Run from:

Component root

Expected output:

Push succeeds and the temporary dev solution updates

Success looks like:

Component behaves in a real form the way it did in the harness

Follows Rule 7

Produces the managed/unmanaged zips that actually travel between environments.

dotnet build /p:configuration=Release

Prerequisites:

Solution folder created with pac solution init and add-reference

Run from:

The solution project folder

Expected output:

bin/Release contains the solution zip(s)

Success looks like:

Zip opens and contains your component with the new version

Follows Rule 8

The sanctioned way a component reaches test or prod.

pac solution import --path {{solution_zip_path}} --environment {{environment_url}} --publish-changes

Careful: Aimed at production this changes what users run — deploy windows and rollback zip first.

Prerequisites:

pac auth profile for the target; System Customizer or higher

Run from:

Anywhere

Expected output:

Import completes and customizations are published

Success looks like:

Component version in the target matches the manifest you shipped

Follows Rule 9

First move when a build fails on one machine but not another.

pac --version; node --version; npm --version

Run from:

Anywhere

Expected output:

Three version lines

Success looks like:

Versions match the pair pinned in the README

Follows Rule 2

The whole journey — from empty folder to a component running in a target environment — with the checks that catch the classic failures before they cost an afternoon.

Prerequisites:

pac CLI authenticated (pac auth create) against both your dev environment and the target; Node LTS installed; solution publisher decided (name + prefix)

Permissions:

System Customizer (or higher) in the target environment

Starting state:

An empty folder for the component, and a sibling empty folder for the solution project

Tools:

pac >=1.30, node >=18, dotnet >=8

1. 1.RunScaffold the component
   ⌘1Scaffold a new PCF componentpowershell

   pac pcf init --namespace {{namespace}} --name {{component_name}} --template {{template}} --run-npm-install

   namespacecomponent_nametemplate

   Copy commandfill {{namespace}}, {{component_name}}, {{template}} to copy

   One component per folder. Template is field for single-value controls, dataset for grids.

   Expect:

   Scaffold files created; npm install runs clean

   Verify:

   ControlManifest.Input.xml exists and npm run build exits 0

2. 2.RunInstall dependencies (if init skipped it)optionalonly when init was run without --run-npm-install

   npm install

   Expect:

   node_modules present, no EPERM errors

   Verify:

   npm run build exits 0

   If it fails here… (1 known failure)

   EPERM/symlink errors on Windows almost always mean Developer Mode is off — see the attached failure note.

   ⚠ pac pcf init fails with EPERM symlink on Windows

   Error: EPERM: operation not permitted, symlink '...' -> '...'

   Likely cause: npm needs to create symlinks; Windows only allows that for unelevated users when Developer Mode is on

   Fix: Enable Windows Developer Mode (Settings → System → For developers), or run the terminal elevated once. Then delete node_modules and re-run npm install.

3. 3.RunProve it in the harness
   ⌘2Run the test harnessbash

   npm start watch

   Copy command

   Exercise every property and both directions of updateView before touching an environment.

   Expect:

   Harness renders the component with live reload

   Verify:

   Property changes in the harness panel visibly re-render the control

4. 4.CheckBump the manifest version

   Open ControlManifest.Input.xml and increment the patch segment of version. Dataverse caches by version — an unchanged number means an unchanged component, whatever you actually shipped.

   Expect:

   Version differs from whatever the target environment currently has

   Verify:

   grep the manifest: the version is new

5. 5.RunCreate the solution project and reference the componentonly when first deployment only — skip when the solution project already exists

   pac solution init --publisher-name {{publisher_name}} --publisher-prefix {{publisher_prefix}} pac solution add-reference --path ../{{component_folder}}

   Expect:

   Solution project created; reference added

   Verify:

   The .cdsproj lists the component project

   If it fails here…

   add-reference stores a relative path; if you later move folders, the build breaks silently — re-add the reference.

6. 6.RunBuild the solution zip
   ⌘4Build the solution packagepowershell

   dotnet build /p:configuration=Release

   Copy command

   Release configuration produces both unmanaged and managed zips when configured.

   Expect:

   bin/Release contains the solution zip

   Verify:

   Unzip and confirm the component and new version are inside

7. 7.DecideDev loop, or a real environment?optionalonly when iterating against your own dev environment
   ⌘3Push to your dev environmentpowershell⚠ Privileged

   pac pcf push --publisher-prefix {{publisher_prefix}}

   publisher_prefix

   Copy commandfill {{publisher_prefix}} to copy

   For your own dev environment, pac pcf push is faster and fine. For anything shared or downstream, only the solution zip travels.

8. 8.RunImport into the target and verify
   ⌘5Import a solution into a target environmentpowershell⚠ Privileged

   pac solution import --path {{solution_zip_path}} --environment {{environment_url}} --publish-changes

   solution_zip_pathenvironment_url

   Copy commandfill {{solution_zip_path}}, {{environment_url}} to copy

   The managed zip goes to test/prod. Publish changes, then open a form that hosts the component.

   Expect:

   Import succeeds; publish completes

   Verify:

   Component renders in a real form AND the shown version matches the manifest

   If it fails here… (1 known failure)

   If behavior is unchanged after import, the version was not bumped (step 4) — see the attached failure note.

   ⚠ Component unchanged in the environment after a successful import

   Import and publish both report success, but the form still runs the old component behavior

   Likely cause: ControlManifest version was not bumped — Dataverse caches component resources by version and treats same-version as no-op

   Fix: Bump the patch version in ControlManifest.Input.xml, rebuild, re-import, publish all customizations. Hard-refresh the browser (the old bundle may also be client-cached).

Success looks like:

The component renders in a real form in the target environment at the manifest version you just shipped

Rollback:

Re-import the previous managed solution zip (kept as a pipeline artifact) with pac solution import, then publish all customizations.

Implements Rule 5, Rule 8, Rule 9

The test harness renders in a bare page with default styling. Model-driven forms inject their own font stack, spacing, and (increasingly) dark-mode tokens. A control that looks pixel-perfect in the harness can look cramped or unreadable in a real form — final visual sign-off has to happen in an environment.

pac solution add-reference writes a relative path into the .cdsproj. Reorganize your folders — even just renaming the component directory — and the solution build fails with a misleading MSBuild error about a missing project. Nothing warns you at rename time. Re-run add-reference after any move.