Edit

Best practices and guidance for code components created using Power Apps component framework

  • Article

Developing, deploying, and maintaining code components needs a combination of knowledge that includes the following:

  • Power Apps component framework
  • Microsoft Power Apps
  • TypeScript and JavaScript
  • HTML Browser User Interface Development
  • Azure DevOps/GitHub

This article outlines established best practices and guidance for professionals developing code components. It aims to provide the benefits behind each so that your code components can take advantage of the usability, supportability, and performance improvements these tools and tips provide.

Power Apps component framework

This section contains best practices and guidance related to Power Apps component framework itself.

Avoid deploying development builds to Dataverse

Code components can be built in production or development mode. Avoid deploying development builds to Dataverse since they adversely affect the performance and can even get blocked from deployment due to their size. Even if you plan to deploy a release build later, it can be easy to forget to redeploy if you don't have an automated release pipeline. More information: Debugging custom controls.

Avoid using unsupported framework methods

These include using undocumented internal methods that exist on the ComponentFramework.Context. These methods may work but, because they're not supported, they may stop working in future versions. Use of control script that accesses host application HTML Document Object Model (DOM) is not supported. Any parts of the host application DOM which are outside the code component boundary, are subject to change without notice.

Use init method to request network required resources

When a code component is loaded by the hosting context, the init method is first called. Use this method to request any network resources such as metadata instead of waiting for the updateView method. If the updateView method is called before the requests return, your code component must handle this state and provide a visual loading indicator.

Clean up resources inside the destroy method

When a code component is removed from the browser DOM, the destroy method is called. Use this method to close any WebSockets and remove event handlers that are added outside of the container element. If you are using React, use ReactDOM.unmountComponentAtNode inside the destroy method. This prevents any performance issues caused by code components being loaded and unloaded within a given browser session.

Avoid unnecessary calls to refresh on a dataset property

If your code component is of type dataset, the bound dataset properties expose a refresh method that causes the hosting context to reload the data. Calling this method unncessarily adversely affects the performance of your code component.

Minimize calls to notifyOutputChanged

In some circumstances, it's undesirable for updates to a UI control (such as keypresses or mouse move events) to each call notifyOutputChanged, as this would result in many more events propagating to the parent context than needed. Instead, consider using an event when a control loses focus, or when the user's touch or mouse event has completed.

Check API availability

When developing code components for different hosts (model-driven apps, canvas apps, portals), always check the availability of the APIs you're using for support on those platforms. For example, context.webAPI is not available in canvas apps. For individual API availability, see Power Apps component framework API reference.

Model-driven apps

This section contains best practices and guidance relating to code components within model-driven apps.

Do not interact directly with formContext

If you have experience working with client API, you may be used to interacting with formContext to access attributes, controls, and call API methods such as save, refresh, and setNotification. Code components are expected to work across various products like model-driven apps, canvas apps, and dashboards, therefore they can't have a dependency on formContext.

A workaround is to make the code component bound to a column and add an OnChange event handler to that column. The code component can update the column value, and the OnChange event handler can access the formContext. Support for the custom events will be added in the future, which will be able to be used for communicating changes outside of a control without adding a column configuration.

Limit size and frequency of calls to the WebApi

When using the context.WebApi methods, limit both the number of calls and the amount of data that's interacted with. Each time you call the WebApi, it will count towards the user's API entitlement and service protection limits. When performing CRUD operations on records, consider the size of the payload. In general, the larger the request payload, the slower your code component will be.

Canvas apps

This section contains best practices and guidance relating to code components within canvas apps.

Minimize the number of components on a screen

Each time you add a component to your canvas app, it takes a finite amount of time to render. The more components you add, the longer the render time will be. Carefully measure the performance of your code components as you add more to a screen using the Developer Performance tools.

Currently, each code component bundles their own library of shared libraries such as Fluent UI and React. Loading multiple instances of the same library will not load these libraries multiple times. However, loading multiple different code components will result in the browser loading multiple bundled versions of these libraries. In the future, these libraries will be able to be loaded and shared with code components.

Allow makers to style your code component

When app makers consume code components from inside a canvas app, they want to use a style that matches the rest of their app. Use input properties to provide customization options for theme elements such as color and size. When using Microsoft Fluent UI, map these properties to the theme elements provided by the library. In the future, theming support will be added to code components to make this process easier.

Follow canvas apps performance best practices

Canvas apps provides a wide set of best practices from inside the app and solution checker. Ensure your apps follow these recommendations before you add code components. For more information, see:

TypeScript and JavaScript

This section contains best practices and guidance relating to TypeScript and JavaScript within code components.

ES5 vs ES6

By default, code components target ES5 to support older browsers. If you don't want to support these older browsers, you can change the target to ES6 inside your pcfproj folder's tsconfig.json. More information: ES5 vs ES6.

Module imports

Always bundle the modules that are required as part of your code component instead of using scripts that are required to be loading using the SCRIPT tag. For example, if you wanted to use a third party charting API where the sample shows adding <script type="text/javascript" src="somechartlibrary.js></script> to the page, this would not be supported inside a code component. Bundling all of the required modules isolates the code component from other libraries and also supports running in offline mode.

Note

Support for shared libraries across components using library nodes in the component manifest is not yet supported.

Linting

Linting is where a tool can scan the code for potential issues. The template used by pac pcf init installs the eslint module to your project and configures it by adding an .eslintrc.json file. Eslint requires configuring for TypeScript and React coding styles. It can also be used to fix some of these issues automatically where possible. To configure, at the command-line use:

npx eslint --init

Then answer the following questions when prompted:

  • How would you like to use ESLint? Answer: To check syntax, find problems, and enforce code style

  • What type of modules does your project use? Answer: JavaScript modules (import/export)

  • Which framework does your project use? Answer: React

  • Does your project use TypeScript? Answer: Yes

  • Where does your code run? Answer: Browser

  • How would you like to define a style for your project? Answer: Answer questions about your style

  • What format do you want your config file to be in? Answer: JSON (This will update the existing .eslintrc.json)

  • What style of indentation do you use? Answer: Spaces (This is the VSCode default)

  • What quotes do you use for strings? Answer: Single

  • What line endings do you use? Answer: Windows (This is the VSCode default CRLF line endings style.)

  • Do you require semicolons? Answer: Yes

Note

You can customize this configuration to suit your particular needs (for example, if you are not using React). More information: Getting started with ESLint.

Before you can use eslint, you need to add some scripts to the package.json:

 "scripts": {
    ...
    "lint": "eslint MY_CONTROL_NAME --ext .ts,.tsx",
    "lint:fix": "npm run lint -- --fix"
  }

The eslint script accepts the folder that contains your code. Replace MY_CONTROL_NAME to be the same name as the code component used when calling pac pcf init.

Now at the command-line, you can use:

npm run lint:fix

This will tidy up code in the project to match your chosen style, and it will also report some issues that will be resolved later.

Note

ESLint will point out problems with the template code initially (e.g. empty constructor). You can add inline comments to instruct ESLint to exclude the rules such as: // eslint-disable-next-line @typescript-eslint/no-empty-function

Additionally, you can add files to ignore (for example, the automatically generated interfaces) by adding the following to the .eslintrc.json:

"ignorePatterns": ["**/generated/*.ts"]

More information: ignorePatterns in config files.

Tip

You can install Visual Studio Code extension that uses the project's .eslintrc.json file to provide code highlighting for any issues detected, with the option to fix them directly inside the IDE. More information: Managing Extensions in Visual Studio Code.

HTML browser user interface development

This section contains best practices and guidance relating to HTML browser UI development.

Use Microsoft Fluent UI React

Fluent UI React is the official open source React front-end framework designed to build experiences that fit seamlessly into a broad range of Microsoft products. Power Apps itself uses Fluent UI, meaning you'll be able to create UI that's consistent with the rest of your apps.

Use path-based imports from Fluent to reduce bundle size

Currently, the code component templates used with pac pcf init will not use tree-shaking, which is the process where webpack detects modules imported that are not used and removes them. This means if you import from Fluent UI using the following, it imports and bundles the entire library:

import { Button } from '@fluentui/react'

To avoid this, you can use path-based imports where the specific library component is imported using the explicit path:

import { Button } from '@fluentui/react/lib/Button';

This reduces your bundle size both in development and release builds.

You can take advantage of tree-shaking (which only affects release/production builds) by updating your tsconfig.json to use the following module configuration inside the compilerOptions section:

"module": "es2015",
"moduleResolution": "node"

More information: Fluent UI - Advanced usage.

Optimize React rendering

When using React, it's important to follow React specific best practices regarding minimizing rendering of components, resulting in a more responsive UI. Some of the best practices are listed below:

  • Only make a call to ReactDOM.render inside the updateView method when a bound property or framework aspect has changed that requires the UI to reflect the change. You can use updatedProperties to determine what has changed.
  • Use PureComponent (with class components) or React.memo (with function components) where possible to avoid unnecessary re-renders of components when its input props have not mutated.
  • For large React components, deconstruct your UI into smaller components to improve performance.
  • Avoid use of arrow functions and function binding inside the render function as this will create a new callback closure with each render and cause the child component to always re-render when the parent component is rendered. Instead, use function binding in the constructor or use class field arrow functions. See Handling Events - React.

Check accessibility

Ensure that code components are accessible and can be used by keyboard only and screen-reader users:

  • Provide keyboard navigation alternatives to mouse/touch events. For example, if your component provides a drop-down list, ensure that a user can use tab to set focus and then navigate the options using the arrow keys.
  • Ensure that alt and ARIA (Accessible Rich Internet Applications) attributes are set so that screen readers will announce an accurate representation of the code components interface. The Microsoft Fluent UI library makes this easy since many of the components are already accessible and screen reader-compatible.
  • Modern browser developer tools offer helpful ways to inspect accessibility. Use these tools to look for common accessibility issues with your code component.

More information: Create accessible canvas apps in Power Apps.

Always use asynchronous network calls

When making network calls, never use a synchronous blocking request since this causes the app to stop responding and result in slow performance. More information: Interact with HTTP and HTTPS resources asynchronously.

Write code for multiple browsers

Model-driven apps, canvas apps, and portals all support multiple browsers. Be sure to only use techniques that are supported on all modern browsers, and test with a representative set of browsers for your intended audience.

Code components should plan for supporting multiple clients and screen formats

Code components can be rendered in multiple clients (model-driven apps, canvas apps, portals) and screen formats (mobile, tablet, web). When used in model-driven apps, dataset code components can be placed on main form grids, related record grids, subgrids, or dashboards. When used in canvas apps, code components can be placed inside responsive containers that resize\ dynamically using the configuration provided by the app maker.

  • Using trackContainerResize allows code components to respond to changes in the available width and height. In some cases, this may mean rendering a different UI that fits the space available. Using allocatedHeight and allocatedWidth can be combined with getFormFactor to determine if the code component is running on a mobile, tablet, or web client. More information: See this Choices picker tutortial.
  • Implementing setFullScreen allows users to expand to use the entire available screen available where space is limited. More information: Canvas app grid component.
  • If the code component cannot provide a meaningful experience in the given container size, it should disable functionality appropriately and provide feedback to the user.

Always use scoped CSS rules

When you implement styling to your code components using CSS, ensure that the CSS is scoped to your component using the automatically generated CSS classes applied to the container DIV element for your component. If your CSS is scoped globally, it will likely break the existing styling of the form or screen where the code component is rendered. If using a third party CSS framework, use a version of that framework that's already namespaced or otherwise wrap that framework in a namespace either by hand or using a CSS preprocessor.

For example, if your namespace is SampleNamespace and your code component name is LinearInputComponent, you would add a custom CSS rule using:

.SampleNamespace\.LinearInputComponent rule-name

Avoid use of web storage objects

Code components should not use the HTML web storage objects, like window.localStorage and window.sessionStorage, to store data. Data stored locally on the user's browser or mobile client is not secure and not guaranteed to be available reliably.

ALM/Azure DevOps/GitHub

See the article on Code component application lifecycle management (ALM) for best practices on code components with ALM/Azure DevOps/GitHub.