{"id":19914718,"url":"https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react","last_synced_at":"2025-04-04T18:05:06.162Z","repository":{"id":37941127,"uuid":"262427583","full_name":"fullstorydev/fullstory-babel-plugin-annotate-react","owner":"fullstorydev","description":"A Babel plugin that annotates React components, making them easier to target with FullStory search","archived":false,"fork":false,"pushed_at":"2025-02-12T01:00:42.000Z","size":8466,"stargazers_count":30,"open_issues_count":13,"forks_count":13,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-03-23T12:35:52.301Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullstorydev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-08T20:58:57.000Z","updated_at":"2024-12-02T17:18:40.000Z","dependencies_parsed_at":"2023-02-19T11:30:32.400Z","dependency_job_id":"b411b6d4-1055-43cc-b232-c52a7b8bc835","html_url":"https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react","commit_stats":{"total_commits":194,"total_committers":18,"mean_commits":"10.777777777777779","dds":0.6185567010309279,"last_synced_commit":"2c534274d0a45cdf97a52561edaf4987b689e959"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Ffullstory-babel-plugin-annotate-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Ffullstory-babel-plugin-annotate-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Ffullstory-babel-plugin-annotate-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Ffullstory-babel-plugin-annotate-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullstorydev","download_url":"https://codeload.github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246948013,"owners_count":20859362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T21:36:51.758Z","updated_at":"2025-04-04T18:05:06.131Z","avatar_url":"https://github.com/fullstorydev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Babel Plugin: Annotate React\n[![CircleCI](https://circleci.com/gh/fullstorydev/fullstory-babel-plugin-annotate-react.svg?style=svg)](https://circleci.com/gh/fullstorydev/fullstory-babel-plugin-annotate-react)\n\nThis is a Babel plugin that annotates React components with stable attributes that can be used to search and select using [FullStory](https://www.fullstory.com/). This is most useful when using a React system that generates dynamic names for Components or rearranges elements.\n\n# Getting started\n\n## with npm\n\n```\nnpm i @fullstory/babel-plugin-annotate-react --save\n```\n\n## with yarn\n\n```\nyarn add @fullstory/babel-plugin-annotate-react\n```\n\n## Babel configuration\n\nAdd the `@fullstory/babel-plugin-annotate-react` plugin to your babel plugin configuration (e.g., **babel.config.js**).\n\n```\nmodule.exports = {\n  /* ... */\n  plugins: [\n    /* ... */\n    \"@fullstory/babel-plugin-annotate-react\"\n  ]\n};\n```\n\n# Description\n\nFor 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`.\n\n\u003e 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***.\n\nThe 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`.\n\nExample input:\n\n    class HelloComponent extends Component {\n      render() {\n        return \u003cdiv\u003e\n          \u003ch1\u003eHello world\u003c/h1\u003e\n        \u003c/div\u003e;\n      }\n    }\n\nExample JS output:\n\n    class HelloComponent extends Component {\n      render() {\n        return React.createElement(\"div\", {\n          \"data-component\": \"HelloComponent\",\n          \"data-file-source\": \"hello-component.js\"\n        }, React.createElement(\"h1\", {\n          null\n        }, \"Hello world\"));\n      }\n    }\n\nFinal render:\n\n    \u003cdiv data-component=\"HelloComponent\" data-file-source=\"hello-component.js\"\u003e\n      \u003ch1\u003eHello world\u003c/h1\u003e\n    \u003c/div\u003e\n\n# Configuration options\n\n## React Native\n\nTo activate React Native support you must pass in a `native` plugin option like so:\n\n    plugins: [\n      [\"@fullstory/babel-plugin-annotate-react\", { native: true }]\n    ]\n\nSee [Getting Started with FullStory React Native Capture](https://help.fullstory.com/hc/en-us/articles/360052419133-Getting-Started-with-FullStory-React-Native-Capture) for more info.\n\n### `setFSTagName` setting\n\nWhen using this library with [FullStory for Mobile Apps](https://www.fullstory.com/platform/mobile-apps/), we recommend setting `setFSTagName: true` to generate better privacy selectors. This setting will automatically set [`fsTagName`](https://developer.fullstory.com/mobile/react-native/auto-capture/set-tag-name/) with the value of `dataElement` or `dataComponent`, which will truncate the privacy selector and avoid duplicate naming.\n\nExample:\n* Before `RCTSafeAreaView[data-source-file=\"App.tsx\"][data-element=\"SafeAreaView\"][data-component=\"App\"]`\n* After `App[data-source-file=\"App.tsx\"]`\n\n```\nplugins: [\n  '@fullstory/react-native',\n  [\"@fullstory/annotate-react\", {\n    native: true,\n    setFSTagName: true,\n  }]\n]\n```\n\n⚠️ Important: Existing FullStory privacy selectors and defined elements may need to be updated if the app was previously published without `setFSTagName: true`.\n\u003c!-- todo: write up a KB article to walk customers through transitioning to `fsTagName` if they have pre-existing privacy selectors or defined elements; link to it here --\u003e\n\n\n## Fragments\n\nBy default, the plugin does not annotate `React.Fragment`s because they may or may not contain a child that ends up being an HTML element.\n\nAn example with no child element:\n\n    const componentName = () =\u003e (\n      \u003cFragment\u003eHello, there.\u003c/Fragment\u003e\n    );\n\nAn example with child elements:\n\n    const componentName = () =\u003e (\n      \u003cFragment\u003e\n        Some text\n        \u003ch1\u003eHello, there.\u003c/h1\u003e /* This one could be annotated */\n        \u003ca href=\"#foo\"\u003eClick me\u003c/a\u003e\n      \u003c/Fragment\u003e\n    );\n\n\nIf 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:\n\n    plugins: [\n      [\"@fullstory/babel-plugin-annotate-react\", { \"annotate-fragments\": true }]\n    ]\n\n## Ignoring Components\n\nIf you would like the plugin to skip the annotation for certain components, use the `ignoreComponents` option:\n\n```javascript\n  plugins: [\n      [\n        \"@fullstory/annotate-react\",\n        {\n          ignoreComponents:[\n            // each item must be a string array containing three items: file name, component name, element name\n            // corresponding to the values for data-source-file, data-component, data-element\n            // use wild card (*) to match anything\n            [\"myBoxComponent.jsx\",\"MyBox\",\"Box\"],\n            [\"App.jsx\", \"*\", \"ThemeProvider\"], // use wild-card to match anything\n            [\"App.jsx\", \"App\", \"*\"],\n          ]\n        }\n      ],\n  ]\n```\n\n## Sample Apps\n\nWe have a few samples to demonstrate this plugin:\n\n- [Single Page App](https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tree/master/samples/single-page-app/)\n- [styled-components](https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tree/master/samples/styled-components/)\n- [React native](https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tree/master/samples/react-native-app/)\n\nMuch of the logic for adding the attributes originated in the [transform-react-qa-classes](https://github.com/davesnx/babel-plugin-transform-react-qa-classes/) plugin.\n\n## Getting Help\n\nPlease refer to our [Knowledge Base article](https://help.fullstory.com/hc/en-us/articles/360049493054-FullStory-s-Annotate-React-plugin-for-Web-Native) or contact mobile-support@fullstory.com for additional help.\n\n### React Native\n\nPlease see our [Getting Started with FullStory React Native Capture](https://help.fullstory.com/hc/en-us/articles/360052419133) guide or email mobile-support@fullstory.com for additional help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstorydev%2Ffullstory-babel-plugin-annotate-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullstorydev%2Ffullstory-babel-plugin-annotate-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstorydev%2Ffullstory-babel-plugin-annotate-react/lists"}