{"id":13400712,"url":"https://github.com/yahoo/react-i13n","last_synced_at":"2025-05-14T21:05:55.008Z","repository":{"id":32513109,"uuid":"36094164","full_name":"yahoo/react-i13n","owner":"yahoo","description":"A performant, scalable and pluggable approach to instrumenting your React application.","archived":false,"fork":false,"pushed_at":"2025-01-16T13:04:47.000Z","size":2684,"stargazers_count":383,"open_issues_count":16,"forks_count":42,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-05T07:06:17.109Z","etag":null,"topics":["instrumentation","react","ui","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2015-05-22T20:37:44.000Z","updated_at":"2025-02-10T11:19:05.000Z","dependencies_parsed_at":"2024-05-06T15:10:43.088Z","dependency_job_id":"77a777fd-2484-42f8-bf32-978367a329a5","html_url":"https://github.com/yahoo/react-i13n","commit_stats":{"total_commits":508,"total_committers":33,"mean_commits":"15.393939393939394","dds":0.5433070866141732,"last_synced_commit":"c9eadee055c5cb87aa1a22c44196fe6244efdf0a"},"previous_names":[],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Freact-i13n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Freact-i13n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Freact-i13n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Freact-i13n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/react-i13n/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227611,"owners_count":22035669,"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":["instrumentation","react","ui","web"],"created_at":"2024-07-30T19:00:54.840Z","updated_at":"2025-05-14T21:05:54.963Z","avatar_url":"https://github.com/yahoo.png","language":"JavaScript","funding_links":[],"categories":["State Management","Code Design","Uncategorized","React [🔝](#readme)"],"sub_categories":["Data Store","Uncategorized"],"readme":"# react-i13n\n\n[![npm version](https://badge.fury.io/js/react-i13n.svg)](http://badge.fury.io/js/react-i13n)\n![Build Status](https://github.com/yahoo/react-i13n/actions/workflows/node.js.yml/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/yahoo/react-i13n/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/yahoo/react-i13n?branch=master)\n\n`react-i13n` provides a performant, scalable and pluggable approach to instrumenting your React application.\n\nTypically, you have to manually add instrumentation code throughout your application, e.g., hooking up `onClick` handlers to the links you want to track. `react-i13n` provides a simplified approach by letting you define the data model you want to track and handling the beaconing for you.\n\n`react-i13n` does this by building an [instrumentation tree](#i13n-tree) that mirrors your applications React component hierarchy. All you have to do is leverage our [React component](./docs/guides/integrateWithComponents.md) to denote which components should fire the tracking events.\n\n## Features\n\n* **i13n tree** - Automated [instrumentation tree](#i13n-tree) creation that mirrors your applications React component hierarchy.\n* **React integration** - Provides a [createI13nNode](./docs/api/createI13nNode.md#createi13nnodecomponent-options) component that easily integrate with your application.\n* **Pluggable** - A pluggable interface lets you integrate any data analytics library (i.e. Google Analytics, Segment, etc). Take a look at the [available plugins](#available-plugins).\n* **Performant** - Tracking data (`i13nModel`) can be a plain JS object or custom function. This means you can [dynamically change tracking data](./docs/guides/integrateWithComponents.md#dynamic-i13n-model) without causing unnecessary re-renders.\n* **Adaptable** - If you are using an isomorphic framework (e.g. [Fluxible](http://fluxible.io)) to build your app, you can easily [change the tracking implementation](./docs/guides/createPlugins.md) on the server and client side. For example, to track page views, you can fire an http request on server and xhr request on the client.\n* **Optimizable** - We provide an option to enable viewport (integrating [subscribe-ui-event](https://github.com/yahoo/subscribe-ui-event)) checking for each `I13nNode`. Which means that data will only be beaconed when the node is in the viewport. This reduces the network usage for the user and provides better tracking details.\n* **Auto Scan Links** - Support [auto scan links](./docs/api/createI13nNode.md) for the cases you are not able to replace the component you are using to get it tracked, e.g., if you have dependencies or you are using `dangerouslySetInnerHTML`. We scan the tags you define on client side, track them and build nodes for them in i13n tree.\n\n## Install\n\n```\nnpm install react-i13n --save\n```\n\n## Runtime Compatibility\n\nreact-i13n is written with ES2015 in mind and should be used along with polyfills\nfor features like [`Promise`][Promise] and [`Object.assign`][objectAssign]\nin order to support all browsers and older versions of Node.js. We recommend using [Babel][babel].\n\n[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise\n[objectAssign]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign\n[babel]: https://babeljs.io/\n\n## Usage\n\n* Choose the appropriate [plugin](#available-plugins).\n* Use the [setupI13n](./docs/api/setupI13n.md) utility to wrap your application component.\n* Define your instrumentation data and [integrate with your components](./docs/guides/integrateWithComponents.md)\n* (Optionally) follow the [event system](./docs/guides/eventSystem.md) if you want to fire events manually.\n\n```js\nimport React, { Component } from 'react';\nimport {\n  ReactI13n,\n  createI13nNode,\n  setupI13n\n} from 'react-i13n';\nimport somePlugin from 'some-i13n-plugin'; // a plugin for a certain instrumentation mechanism\n\n// create a i13n anchor for link tracking\nconst I13nAnchor = createI13nNode('a', {\n  isLeafNode: true,\n  bindClickEvent: true,\n  follow: true\n});\n\nclass DemoApp extends Component {\n  componentDidMount () {\n    // fire a custom event\n    this.props.i13n.executeEvent('pageview', {});\n  }\n\n  render() {\n    \u003cspan\u003e\n      \u003cI13nAnchor\n        href=\"http://foo.bar\"\n        i13nModel={{\n          action: 'click',\n          label: 'foo'\n        }}\n      \u003e\n        ...\n      \u003c/I13nAnchor\u003e\n      // this link will be tracked, and the click event handlers provided by the plugin will get the model data as\n      // {site: 'foo', action: 'click', label: 'foo'}\n    \u003c/span\u003e\n  }\n};\n\n\nconst I13nDempApp = setupI13n(DemoApp, {\n  rootModelData: { site: 'foo' },\n  isViewportEnabled: true\n}, [somePlugin]);\n\n// then you could use I13nDemoApp to render you app\n```\n\n## Available Plugins\n* [react-i13n-ga](https://github.com/kaesonho/react-i13n-ga) - Google Analytics plugin\n* [react-i13n-mixpanel](https://github.com/adlenafane/react-i13n-mixpanel) - Mixpanel plugin\n* [react-i13n-segment](https://github.com/adlenafane/react-i13n-segment) - Segment plugin\n\nOr follow our guide and [create your own](./docs/guides/createPlugins.md).\n\n## I13n Tree\n![I13n Tree](https://cloud.githubusercontent.com/assets/3829183/7980892/0b38eb70-0a60-11e5-8cc2-712ec42089fc.png)\n\n`react-i13n` builds the instrumentation tree by leveraging the React `context` feature. Each component can define a `i13nModel` prop that defines the data it needs to track. This approach is more performant, as it means you do not need additional DOM manipulation when you want to collect the tracking data values for sending out beacons.\n\nSince the i13n data is defined at each level. Whenever you want to get the `i13nModel` for a certain node, `react-i13n` will traverse back up the tree to merge all the `i13nModel` information in the hierarchy. Since the tree is already built, you do not need extra DOM access, which is cheap and efficient.\n\n## Performance\n\nThe performance has always been a topic we are working on, and yes it's an overhead to create an additional react component wrapping the link, the performance benchmark as below:\n\n```\nlink-without-react-component x 131,232 ops/sec ±1.08% (82 runs sampled)\nlink-wrapped-with-react-component x 111,056 ops/sec ±1.55% (88 runs sampled)\nlink-wrapped-with-react-component-with-i13n-high-order-component x 64,422 ops/sec ±1.95% (84 runs sampled)\n```\n\n## Presentation\nTake a look at [Rafael Martins' slides](http://www.slideshare.net/RafaelMartins21/instrumentation-talk-39547608) from a recent React meetup to understand more.\n\n## Debugging\nAdd `i13n_debug=1` to the request url, you will get the i13n model for each `i13n node` directly shown on the page. It shows the information for each model data and where the data inherits from.\n\n## Examples\n* [react-i13n-flux-examples](https://github.com/kaesonho/react-i13n-flux-examples) - we forked the [flux examples](https://github.com/facebook/flux/tree/master/examples) and integrated `react-i13n` with it.\n* [fluxible.io](http://fluxible.io/) - [fluxible](https://github.com/yahoo/fluxible) site integrating `react-i13n` and [react-i13n-ga](https://github.com/kaesonho/react-i13n-ga).\n\n## Set ENV during CI process\nWe check `process.env.NODE_ENV !== 'production'` to determine if we should do some action like print out warning message, that means it's recommended to use tools like `envify` as part of your build process to strip out non-production code for production build.\n\n### With Webpack\n\nUse `DefinePlugin` to define the value for `process.env`.\n\n```js\n// Example of the webpack configuration:\n\nplugins: [\n  new webpack.DefinePlugin({\n    'process.env': {\n        NODE_ENV: JSON.stringify('production')\n    }\n  }),\n  ...\n]\n```\n\n### With Browserify\n\nSimilar to webpack, you can also use `envify` to set process.env.NODE_ENV to the desired environment\n\n```bash\n$ browserify index.js -t [ envify --NODE_ENV production  ] | uglifyjs -c \u003e bundle.js\n\n```\n\n## Testing\n\n### Unit\n\n* `grunt unit` to run unit tests\n* `grunt cover` to generate the istanbul coverage report\n\n### Functional\n\n* debug locally:\n   * `grunt functional-debug`\n   * check functional testing result on `http://127.0.0.1:9999/tests/functional/page.html`\n* run functional test on `saucelabs`:\n   * make sure you have a saucelab account setup, get the user id ane the access key\n   * setup [sauce-connect](https://docs.saucelabs.com/reference/sauce-connect/)\n   * `SAUCE_USERNAME={id} SAUCE_ACCESS_KEY={accessKey} grunt functional`\n\n## License\n\nThis software is free to use under the Yahoo Inc. BSD license.\nSee the [LICENSE file](./LICENSE.md) for license text and copyright information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Freact-i13n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Freact-i13n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Freact-i13n/lists"}