React is a popular JavaScript library that provides a way for software developers to quickly create user interfaces for the web in a declarative fashion. Part of the way React works is that it dynamically generates classes such as class="Azc44GrPgUQwaMdsxT21g RSzhz6gmPB1iAe-9l8gXJ".
While this level of abstraction is okay for the software developer and end user, when third party tools like Fullstory try to provide a way for businesses to search across their users’ digital experience, these dynamically generated names don’t appear to make sense.
To address this shortcoming with React and Fullstory, our product team developed an open source Babel plugin called Annotate React that automatically adds stable attributes. Now, identifying your components is easy and resilient.
Using stable attributes with your React DOM unlocks several key benefits when using Fullstory:
- These defined attributes are automatically suggested in search.
- Engagement Heatmaps and Click Maps (for Web) can accurately count element interactions.
- Selectors used for segments, Watched Elements, and privacy rules remain stable over time (and are much easier to understand across your organization).
What exactly does the plugin do?
For React, the babel plugin annotates components with attributes of data-component, data-element, and data-source-file.
For React Native, the attributes are dataComponent, dataElement, and dataSourceFile.
The component attribute names the React.Component. The element attribute names dynamically emitted DOM or native elements so that you can select by emitter names like View or Image. The source file attribute names the source file that the component came from.
It's important to note that by design, the plugin will never overwrite a pre-existing attribute.
To see the plugin in action, consider the following example input:
class HelloComponent extends Component {
render() {
return <div>
<h1>Hello world</h1>
</div>;
}
Note the lack of any CSS selector that could be used to reliably identify this unique element.
Now compare this to the final render after using the Annotate React plugin:
<div data-component="HelloComponent" data-file-source="hello-component.js">
<h1>Hello world</h1>
</div>
Now we can now reliably identify this element with a stable selector!
What libraries are supported by Fullstory's Annotate React plugin?
The plugin was specifically designed to support React and React Native. It is also compatible with most CSS-in-JS libraries, including Styled-Components.
How to install the Fullstory's Annotate React plugin
The Annotate React plugin is an open source project actively maintained by Fullstory and available on Github.
Full documentation to install and run the plugin can be found here: https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react
NPM installation can be found here:
https://www.npmjs.com/package/@fullstory/babel-plugin-annotate-react
Note: This plugin is not retroactive. Since the plugin is adding attributes before capture, it can only apply for new sessions going forward.