npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@fullstory/babel-plugin-annotate-react

v2.3.1

Published

A Babel plugin that annotates React components, making them easier to target with FullStory search

Downloads

126,009

Readme

Babel Plugin: Annotate React

CircleCI

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.

Getting started

with npm

npm i @fullstory/babel-plugin-annotate-react --save

with yarn

yarn add @fullstory/babel-plugin-annotate-react

Babel configuration

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"
  ]
};

Description

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>

Configuration options

React Native

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.

setFSTagName setting

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,
  }]
]

⚠️ Important: Existing FullStory privacy selectors and defined elements may need to be updated if the app was previously published without setFSTagName: true.

Fragments

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 }]
]

Ignoring Components

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", "*"],
          ]
        }
      ],
  ]

Sample Apps

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.

Getting Help

Please refer to our Knowledge Base article or contact [email protected] for additional help.

React Native

Please see our Getting Started with FullStory React Native Capture guide or email [email protected] for additional help.