Skip to content

Commit 91d587e

Browse files
lxsmnsycRobPruzan
lxsmnsyc
and
RobPruzan
authored
fix: react-scan README (#237)
* Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * reflect changes * Add `React Router` * Update README.md * Remove roadmap * Rework docs * Fix links * Update astro.md * Add `is:inline` * Update remix.md * Update react-router.md * Fix remix docs * Update remix.md * Update tanstack-start.md * Update react-router.md * Update next-js-app-router.md * Update next-js-page-router.md * Update parcel.md * chore: wording change to sync with roadmap removed --------- Co-authored-by: RobPruzan <[email protected]>
1 parent 4560e31 commit 91d587e

File tree

11 files changed

+615
-406
lines changed

11 files changed

+615
-406
lines changed

‎README.md‎

Lines changed: 46 additions & 204 deletions
Original file line numberDiff line numberDiff line change
@@ -27,121 +27,42 @@ Airbnb&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://polaris.shopify.com/"
2727
2828
## Install
2929

30-
Add this script to your app:
30+
### Package managers
3131

32-
```html
33-
<!-- import this BEFORE any scripts -->
34-
<script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
32+
```bash
33+
npm i react-scan
3534
```
3635

37-
Examples:
38-
39-
<details>
40-
<summary><b>Next.js (pages)</b></summary>
41-
42-
<br />
43-
44-
Add the script tag to your `pages/_document.tsx`:
45-
46-
```jsx
47-
import { Html, Head, Main, NextScript } from 'next/document';
48-
49-
export default function Document() {
50-
return (
51-
<Html lang="en">
52-
<Head>
53-
<script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
54-
55-
{/* rest of your scripts go under */}
56-
</Head>
57-
<body>
58-
<Main />
59-
<NextScript />
60-
</body>
61-
</Html>
62-
);
63-
}
36+
```bash
37+
pnpm add react-scan
6438
```
6539

66-
</details>
67-
68-
<details>
69-
<summary><b>Next.js (app)</b></summary>
70-
71-
<br />
72-
73-
Add the script tag to your `app/layout.tsx`:
74-
75-
```jsx
76-
export default function RootLayout({
77-
children,
78-
}: {
79-
children: React.ReactNode
80-
}) {
81-
return (
82-
<html lang="en">
83-
<head>
84-
<script src="https://unpkg.com/react-scan/dist/auto.global.js" async />
85-
{/* rest of your scripts go under */}
86-
</head>
87-
<body>{children}</body>
88-
</html>
89-
)
90-
}
40+
```bash
41+
yarn add react-scan
9142
```
9243

93-
</details>
94-
95-
<details>
96-
<summary><b>Vite / Create React App</b></summary>
97-
98-
<br />
99-
100-
Add the script tag to your `index.html`:
44+
### CDN
10145

10246
```html
103-
<!doctype html>
104-
<html lang="en">
105-
<head>
106-
<script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
107-
108-
<!-- rest of your scripts go under -->
109-
</head>
110-
<body>
111-
<!-- ... -->
112-
</body>
113-
</html>
114-
```
115-
116-
</details>
117-
118-
If you want to install the Chrome extension, follow the guide [here](https://github.com/aidenybai/react-scan/blob/main/BROWSER_EXTENSION_GUIDE.md), or React Native support, see [here](https://github.com/aidenybai/react-scan/pull/23).
119-
120-
## API Reference
121-
122-
If you need a programmatic API to debug further, install via NPM instead:
123-
124-
```bash
125-
npm install react-scan
47+
<!-- import this BEFORE any scripts -->
48+
<script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
12649
```
12750

128-
Then, in your app, import this **BEFORE** `react`. This must run in a client context (e.g. not in a server component):
51+
## Usage
12952

130-
```js
131-
import { scan } from 'react-scan'; // import this BEFORE react
132-
import React from 'react';
53+
- [NextJS App Router](https://github.com/aidenybai/react-scan/blob/main/docs/installation/next-js-app-router.md)
54+
- [NextJS Page Router](https://github.com/aidenybai/react-scan/blob/main/docs/installation/next-js-page-router.md)
55+
- [Create React App](https://github.com/aidenybai/react-scan/blob/main/docs/installation/create-react-app.md)
56+
- [Vite](https://github.com/aidenybai/react-scan/blob/main/docs/installation/vite.md)
57+
- [Parcel](https://github.com/aidenybai/react-scan/blob/main/docs/installation/parcel.md)
58+
- [Remix](https://github.com/aidenybai/react-scan/blob/main/docs/installation/remix.md)
59+
- [React Router](https://github.com/aidenybai/react-scan/blob/main/docs/installation/react-router.md)
60+
- [Astro](https://github.com/aidenybai/react-scan/blob/main/docs/installation/astro.md)
61+
- [TanStack Start](https://github.com/aidenybai/react-scan/blob/main/docs/installation/tanstack-start.md)
13362

134-
if (typeof window !== 'undefined') {
135-
scan({
136-
enabled: true,
137-
log: true, // logs render info to console (default: false)
138-
});
139-
}
140-
```
63+
### CLI
14164

142-
> Looking for [React Native](https://github.com/aidenybai/react-scan/pull/23)?
143-
144-
If you don't have a local version of the site, you can use the CLI. This will spin up an isolated browser instance which you can interact or use React Scan with.
65+
If you don't have a local version of the site or you want to test a React app remotely, you can use the CLI. This will spin up an isolated browser instance which you can interact or use React Scan with.
14566

14667
```bash
14768
npx react-scan@latest http://localhost:3000
@@ -160,6 +81,14 @@ You can add it to your existing dev process as well. Here's an example for Next.
16081
}
16182
```
16283

84+
### Browser Extension
85+
86+
If you want to install the Chrome extension, follow the guide [here](https://github.com/aidenybai/react-scan/blob/main/BROWSER_EXTENSION_GUIDE.md).
87+
88+
### React Native
89+
90+
See [discussion](https://github.com/aidenybai/react-scan/pull/23)
91+
16392
## API Reference
16493

16594
<details>
@@ -178,113 +107,65 @@ export interface Options {
178107
* @default true
179108
*/
180109
enabled?: boolean;
181-
/**
182-
* Include children of a component applied with withScan
183-
*
184-
* @default true
185-
*/
186-
includeChildren?: boolean;
187110

188111
/**
189-
* Enable/disable geiger sound
112+
* Force React Scan to run in production (not recommended)
190113
*
191-
* @default true
114+
* @default false
192115
*/
193-
playSound?: boolean;
194-
116+
dangerouslyForceRunInProduction?: boolean;
195117
/**
196118
* Log renders to the console
197119
*
120+
* WARNING: This can add significant overhead when the app re-renders frequently
121+
*
198122
* @default false
199123
*/
200124
log?: boolean;
201125

202126
/**
203127
* Show toolbar bar
204128
*
129+
* If you set this to true, and set {@link enabled} to false, the toolbar will still show, but scanning will be disabled.
130+
*
205131
* @default true
206132
*/
207133
showToolbar?: boolean;
208134

209-
/**
210-
* Render count threshold, only show
211-
* when a component renders more than this
212-
*
213-
* @default 0
214-
*/
215-
renderCountThreshold?: number;
216-
217-
/**
218-
* Clear aggregated fibers after this time in milliseconds
219-
*
220-
* @default 5000
221-
*/
222-
resetCountTimeout?: number;
223-
224-
/**
225-
* Maximum number of renders for red indicator
226-
*
227-
* @default 20
228-
* @deprecated
229-
*/
230-
maxRenders?: number;
231-
232-
/**
233-
* Report data to getReport()
234-
*
235-
* @default false
236-
*/
237-
report?: boolean;
238-
239-
/**
240-
* Always show labels
241-
*
242-
* @default false
243-
*/
244-
alwaysShowLabels?: boolean;
245-
246135
/**
247136
* Animation speed
248137
*
249138
* @default "fast"
250139
*/
251-
animationSpeed?: 'slow' | 'fast' | 'off';
252-
253-
/**
254-
* Smoothly animate the re-render outline when the element moves
255-
*
256-
* @default true
257-
*/
258-
smoothlyAnimateOutlines?: boolean;
140+
animationSpeed?: "slow" | "fast" | "off";
259141

260142
/**
261143
* Track unnecessary renders, and mark their outlines gray when detected
262144
*
263-
* An unnecessary render is defined as a component re-rendering with no change to the component's corresponding dom subtree (e.g. a component re-rendered, but nothing in the components UI did not change)
145+
* An unnecessary render is defined as the component re-rendering with no change to the component's
146+
* corresponding dom subtree
264147
*
265-
* @default true
148+
* @default false
266149
* @warning tracking unnecessary renders can add meaningful overhead to react-scan
267150
*/
268151
trackUnnecessaryRenders?: boolean;
269152

270153
onCommitStart?: () => void;
271-
onRender?: (fiber: Fiber, render: Render) => void;
154+
onRender?: (fiber: Fiber, renders: Array<Render>) => void;
272155
onCommitFinish?: () => void;
273-
onPaintStart?: (outlines: PendingOutline[]) => void;
274-
onPaintFinish?: (outlines: PendingOutline[]) => void;
156+
onPaintStart?: (outlines: Array<Outline>) => void;
157+
onPaintFinish?: (outlines: Array<Outline>) => void;
275158
}
276159
```
277160

278161
</details>
279162

280163
- `scan(options: Options)`: Imperative API to start scanning
281164
- `useScan(options: Options)`: Hook API to start scanning
282-
- `withScan(Component, options: Options)`: Whitelist a specific component, do not scan other components
283165
- `getReport()`: Get a report of all the renders
284166
- `setOptions(options: Options): void`: Set options at runtime
285167
- `getOptions()`: Get the current options
286168
- `onRender(Component, onRender: (fiber: Fiber, render: Render) => void)`: Hook into a specific component's renders
287-
- `getRenderInfo(Component)`: Get the render info for a specific component
288169

289170
## Why React Scan?
290171

@@ -297,7 +178,7 @@ However, this makes it easy to accidentally cause unnecessary renders, making th
297178
This often comes down to props that update in reference, like callbacks or object values. For example, the `onClick` function and `style` object are re-created on every render, causing `ExpensiveComponent` to slow down the app:
298179

299180
```jsx
300-
<ExpensiveComponent onClick={() => alert('hi')} style={{ color: 'purple' }} />
181+
<ExpensiveComponent onClick={() => alert("hi")} style={{ color: "purple" }} />
301182
```
302183

303184
React Scan helps you identify these issues by automatically detecting and highlighting renders that cause performance issues. Now, instead of guessing, you can see exactly which components you need to fix.
@@ -320,17 +201,7 @@ Also, some personal complaints about React Devtools' highlight feature:
320201
- No programmatic API
321202
- It's stuck in a chrome extension, I want to run it anywhere on the web
322203
- It looks subjectively ugly (lines look fuzzy, feels sluggish)
323-
- I'm more ambitious with react-scan (see our roadmap)
324-
325-
**Q: React Native wen?**
326-
327-
Soon :)
328-
329-
**Q: Browser Extension wen?**
330-
331-
The browser extension is available for Chrome, Firefox, and Brave, but it's awaiting approval from browser extension stores.
332-
333-
In the meanwhile, you can install it manually by following the instructions in [BROWSER_EXTENSION_GUIDE.md](BROWSER_EXTENSION_GUIDE.md).
204+
- I'm more ambitious with react-scan
334205

335206
## Resources & Contributing Back
336207

@@ -346,35 +217,6 @@ We expect all contributors to abide by the terms of our [Code of Conduct](https:
346217

347218
[**→ Start contributing on GitHub**](https://github.com/aidenybai/react-scan/blob/main/.github/CONTRIBUTING.md)
348219

349-
## Roadmap
350-
351-
- [x] Scan only for unnecessary renders ("unstable" props)
352-
- [x] Scan API (`withScan`, `scan`)
353-
- [x] Cleanup config options
354-
- [x] Chrome extension (h/t [@biw](https://github.com/biw))
355-
- [x] Mode to highlight long tasks
356-
- [x] Add context updates
357-
- [x] Expose primitives / internals for advanced use cases
358-
- [x] More explicit options override API (start log at certain area, stop log, etc.)
359-
- [x] Don't show label if no reconciliation occurred ("client renders" in DevTools)
360-
- [x] "global" counter using `sessionStorage`, aggregate count stats instead of immediate replacement
361-
- [x] Give a general report of the app's performance
362-
- [x] Select areas of the screen to scan
363-
- [x] Report should include all renders
364-
- [x] heatmap decay (stacked renders will be more intense)
365-
- [x] Investigate components (UI allowlist)
366-
- [ ] Offscreen canvas on worker thread
367-
- [ ] UI for turning on/off options
368-
- [ ] “PageSpeed insights” for React
369-
- [ ] CLI
370-
- [ ] React Native support
371-
- [ ] Cleanup API reference
372-
- [ ] Name / explain the actual problem, docs
373-
- [ ] Simple FPS counter
374-
- [ ] [Runtime version guarding](https://github.com/lahmatiy/react-render-tracker/blob/229ad0e9c28853615300724d5dc86c140f250f60/src/publisher/react-integration/utils/getInternalReactConstants.ts#L28)
375-
- [ ] React as peer dependency (lock version to range)
376-
- [ ] Add a funny mascot, like the ["Stop I'm Changing" dude](https://www.youtube.com/shorts/FwOZdX7bDKI?app=desktop)
377-
378220
## Acknowledgments
379221

380222
React Scan takes inspiration from the following projects:

‎docs/installation/astro.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Astro Guide
2+
3+
## As a script tag
4+
5+
Add the script tag to your root layout
6+
7+
```astro
8+
<!doctype html>
9+
<html lang="en">
10+
<head>
11+
<script is:inline src="https://unpkg.com/react-scan/dist/auto.global.js" />
12+
13+
<!-- rest of your scripts go under -->
14+
</head>
15+
<body>
16+
<!-- ... -->
17+
</body>
18+
</html>
19+
```
20+
21+
## As a module import
22+
23+
Add the script to your root layout
24+
25+
```astro
26+
<!doctype html>
27+
<html lang="en">
28+
<head>
29+
<script>
30+
import { scan } from 'react-scan';
31+
32+
scan({
33+
enabled: true,
34+
});
35+
</script>
36+
<!-- rest of your scripts go under -->
37+
</head>
38+
<body>
39+
<!-- ... -->
40+
</body>
41+
</html>
42+
```

0 commit comments

Comments
 (0)