https://github.com/oslabs-beta/react-pinpoint
An open source utility library for measuring React component render times.
https://github.com/oslabs-beta/react-pinpoint
default-threshold docker docker-compose performance performance-metrics performance-visualization puppeteer react react-components reactjs speed test testing
Last synced: 2 months ago
JSON representation
An open source utility library for measuring React component render times.
- Host: GitHub
- URL: https://github.com/oslabs-beta/react-pinpoint
- Owner: oslabs-beta
- License: mit
- Created: 2020-07-25T15:43:06.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-10-19T14:56:16.000Z (over 4 years ago)
- Last Synced: 2025-01-15T08:09:45.450Z (3 months ago)
- Topics: default-threshold, docker, docker-compose, performance, performance-metrics, performance-visualization, puppeteer, react, react-components, reactjs, speed, test, testing
- Language: JavaScript
- Homepage: https://reactpinpoint.com
- Size: 784 KB
- Stars: 93
- Watchers: 6
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Pinpoint
An open source utility library for measuring React component render times.
[](https://travis-ci.org/joemccann/dillinger)
## Table of Contents
- [Prerequisites](#prerequisites)
- [Browser context](#browser-context)
- [Production build with a twist](#production-build-with-a-twist)
- [APIs](#apis)
- [record](#record--)
- [report](#report--)
- [Examples](#examples)
- [Using with Puppeteer](#using-with-puppeteer)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Docker](#docker)
- [FAQS](#faqs)
## Prerequisites
### Browser context
React pinpoint must run inside a browser context to observe the React fiber tree. We recommended using automation software such as
[puppeteer](https://github.com/puppeteer/puppeteer) to achieve this.
### Production build with a twist
React optimises your development code base when you build for production, which decreases component render times. Users should therefore run
react pinpoint against their production code
However, tweaks need to be made to the build process to preserve component names and enable render time profiling. Steps for doing so can be
[found here](https://gist.github.com/bvaughn/25e6233aeb1b4f0cdb8d8366e54a3977).
## APIs
### `record(page, url, rootId)`
- `page` <[Page](https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md#class-page)> Puppeteeer page instance
- `url` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)> address React page is hosted at
- `rootId` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)> id of dom element that React is
mounted to
- returns: <[Page](https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md#class-page)> Puppeteeer page instance with a listener
attached to React components
This function attaches a listener to the Puppeteer page's react root for recording changes
### `report(page, threshold)`
- `page` <[Page](https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md#class-page)> Puppeteeer page instance with record listener
attached
- `threshold` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)> cutoff for acceptable
component render time (in ms)
- default time is 16ms
- returns: [Node[]](https://developer.mozilla.org/en-US/docs/Glossary/array) An array of nodes belonging to each react component that
exceeded the given render time threshold
Will report all component render times that exceed the given threshold in ms
If no threshold is given, the default threshold of 16ms is used (please see [FAQ “Why is the default render threshold 16ms?”](<(#faqs)>))
## Examples
### Using with Puppeteer
```javascript
const puppeteer = require('puppeteer');
const reactPinpoint = require('react-pinpoint');
(async () => {
const browser = await puppeteer.launch({});
const page = await browser.newPage();
// Pass information to
const url = 'http://localhost:3000/calculator';
const rootId = '#root';
await reactPinpoint.record(page, url, rootId);
// Perform browser actions
await page.click('#yeah1');
await page.click('#yeah2');
await page.click('#yeah3');
// Get all components that took longer than 16ms to render during browser actions
const threshold = 16;
const slowRenders = await reactPinpoint.reportTestResults(page, threshold);
await browser.close();
})();
```
## Getting Started
1. Head over to the React Pinpoint [website](https://reactpinpoint.com).
2. Register for an account.
3. Add a project and fill in the details.
4. Copy the project ID provided.
## Installation
Using npm:
```shell
npm install -D react-pinpoint
```
Using yarn:
```shell
yarn add react-pinpoint -D
```
- Invoke `mountToReactRoot` and paste the project ID you received from the website as the second argument in your React project’s entry file:
```javascript
mountToReactRoot(rootDom, projectID);
```
- Interact with your app and data will be sent to React Pinpoint website.
- Refresh the page and see your data displayed!
## Docker
React pinpoint was designed with the goal of regression testing component render times within a CICD, we therefore offer several
preconfigured docker containers to assist with using React pinpoint within a CICD as well as with examples for doing so.
- [Puppeteer](https://github.com/oslabs-beta/react-pinpoint/tree/master/dockerfile-generator)
## FAQs
#### Why does React Pinpoint only measure individual component render times?
Since React has moved to using a React Fiber infrastructure, different component types are assumed to generate different trees.
#### Why is the default render threshold 16ms?
The recommended render time is [60 FPS](https://developers.google.com/web/fundamentals/performance/rendering).
#### Does React pinpoint work in a headless browser?
Yes! Due to the component render times being driven by component logic, a GUI is not needed to capture them.