This is a Babel plugin that annotates React components with stable attributes that can be used to search and select using FullStory. This is most useful when using a React system that generates dynamic names for Components or rearranges elements.
npm i @fullstory/babel-plugin-annotate-react --save
yarn add @fullstory/babel-plugin-annotate-react
Add the @fullstory/babel-plugin-annotate-react plugin to your babel plugin configuration (e.g., babel.config.js).
module.exports = {
/* ... */
plugins: [
/* ... */
"@fullstory/babel-plugin-annotate-react"
]
};
For React on the web, the attributes data-component, data-element, and data-source-file are added to each element. For React Native, the attributes added are dataComponent, dataElement, and dataSourceFile.
Note that for both web and native, these attributes will appear as kebab-case in the Fullstory application due to backend processing. End users of Fullstory should create search filters (i.e. segments, metrics, etc) using kebab-case.
The component attribute names the React.Component and the element attribute names the original native elements like View or Image or an emitter of DOM elements like Fragment.
Example input:
class HelloComponent extends Component {
render() {
return <div>
<h1>Hello world</h1>
</div>;
}
}
Example JS output:
class HelloComponent extends Component {
render() {
return React.createElement("div", {
"data-component": "HelloComponent",
"data-file-source": "hello-component.js"
}, React.createElement("h1", {
null
}, "Hello world"));
}
}
Final render:
<div data-component="HelloComponent" data-file-source="hello-component.js">
<h1>Hello world</h1>
</div>
To activate React Native support you must pass in a native plugin option like so:
plugins: [
["@fullstory/babel-plugin-annotate-react", { native: true }]
]
See Getting Started with FullStory React Native Capture for more info.
When using this library with FullStory for Mobile Apps, we recommend setting setFSTagName: true to generate better privacy selectors. This setting will automatically set fsTagName with the value of dataElement or dataComponent, which will truncate the privacy selector and avoid duplicate naming.
Example:
- Before
RCTSafeAreaView[data-source-file="App.tsx"][data-element="SafeAreaView"][data-component="App"] - After
App[data-source-file="App.tsx"]
plugins: [
'@fullstory/react-native',
["@fullstory/annotate-react", {
native: true,
setFSTagName: true,
}]
]
setFSTagName: true.
By default, the plugin does not annotate React.Fragments because they may or may not contain a child that ends up being an HTML element.
An example with no child element:
const componentName = () => (
<Fragment>Hello, there.</Fragment>
);
An example with child elements:
const componentName = () => (
<Fragment>
Some text
<h1>Hello, there.</h1> /* This one could be annotated */
<a href="#foo">Click me</a>
</Fragment>
);
If you would like the plugin to attempt to annotate the first HTML element created by a Fragment (if it exists) then set the annotate-fragments flag:
plugins: [
["@fullstory/babel-plugin-annotate-react", { "annotate-fragments": true }]
]
If you would like the plugin to skip the annotation for certain components, use the ignoreComponents option:
plugins: [
[
"@fullstory/annotate-react",
{
ignoreComponents:[
// each item must be a string array containing three items: file name, component name, element name
// corresponding to the values for data-source-file, data-component, data-element
// use wild card (*) to match anything
["myBoxComponent.jsx","MyBox","Box"],
["App.jsx", "*", "ThemeProvider"], // use wild-card to match anything
["App.jsx", "App", "*"],
]
}
],
]We have a few samples to demonstrate this plugin:
Much of the logic for adding the attributes originated in the transform-react-qa-classes plugin.
Please refer to our Knowledge Base article or contact [email protected] for additional help.
Please see our Getting Started with FullStory React Native Capture guide or email [email protected] for additional help.