Integrating Third-Party Libraries like Highcharts into a PCF Control

Step by step

Follow these steps to scaffold the control, add Highcharts, wire up the loading strategy, and manage the lifecycle. Step four is only needed if you externalize the library.

1. 1

   Scaffold the PCF control

   Create the control project with the Power Platform CLI. Run pac pcf init with a namespace, a control name, and the field template, then run npm install. This gives you the standard PCF structure: ControlManifest.Input.xml, an index.ts that implements ComponentFramework.StandardControl, and the pcf-scripts build pipeline.

   pac pcf init --namespace Solzet --name HighchartsChart --template field
   npm install

2. 2

   Add Highcharts as a dependency

   Install Highcharts from npm. Highcharts ships its own TypeScript definitions, so no separate types package is needed. Import it in index.ts as a namespace so the typed Options and Chart interfaces are available to you.

   npm install highcharts

   import * as Highcharts from 'highcharts';

3. 3

   Decide how to load it: bundle or externalize

   By default webpack bundles Highcharts into your control. If you prefer to load it from a CDN to keep the bundle small, enable custom webpack in featureconfig.json and add a webpack.config.js that marks highcharts as an external. That tells webpack the import should resolve to the global Highcharts object at runtime rather than being bundled.

   {
     "pcfAllowCustomWebpack": "on"
   }

   // Merged into the PCF webpack build when custom webpack is enabled.
   // "highcharts" is now expected as a global at runtime, not bundled.
   module.exports = {
     externals: {
       highcharts: 'Highcharts'
     }
   };

4. 4

   Load the CDN script when externalizing

   When Highcharts is external, the global must exist before your code uses it. Inject the CDN script once during init and resolve a promise when it loads. If you bundled Highcharts instead, skip this step, because the library is already inside your control.

   private loadHighcharts(): Promise<void> {
     if ((window as unknown as { Highcharts?: unknown }).Highcharts) {
       return Promise.resolve();
     }
     return new Promise((resolve, reject) => {
       const script = document.createElement('script');
       script.src = 'https://code.highcharts.com/highcharts.js';
       script.onload = () => resolve();
       script.onerror = () => reject(new Error('Highcharts failed to load'));
       document.head.appendChild(script);
     });
   }

5. 5

   Render the chart in updateView, create once and update in place

   Build the chart options from your bound parameters. In updateView, if no chart instance exists yet, create it with Highcharts.chart against your container element; otherwise call chart.update with the new options. Recreating the chart on every updateView call is the most common cause of flicker and leaked DOM nodes.

   public updateView(context: ComponentFramework.Context<IInputs>): void {
     const options: Highcharts.Options = {
       chart: { type: 'column' },
       title: { text: context.parameters.chartTitle.raw ?? '' },
       series: [{ type: 'column', data: this.readData(context) }]
     };
   
     if (!this.chart) {
       // Create once against the container the platform gave us in init.
       this.chart = Highcharts.chart(this.container, options);
     } else {
       // Update in place on every later render: no flicker, no leaked DOM.
       this.chart.update(options, true, true);
     }
   }

6. 6

   Destroy the chart to avoid memory leaks

   The platform calls destroy when the control is removed. Highcharts attaches window resize listeners and SVG DOM, so you must call chart.destroy there and drop the reference. Without it, navigating between records or re-rendering a grid leaks a chart instance and its listeners every time.

   public destroy(): void {
     // Releases Highcharts SVG, event handlers, and window resize listeners.
     this.chart?.destroy();
     this.chart = undefined;
   }

7. 7

   Build, test, and package

   Run npm run build to compile and bundle the control, then npm start watch to test it in the local PCF harness with sample data. When it works, package it into a solution with the pac solution commands and import it to test inside a real model-driven app.

   npm run build
   npm start watch

Common pitfalls

Most problems with a third-party library inside PCF come down to the lifecycle. These are the ones we correct most often when reviewing controls.