https://github.com/margelo/react-native-release-profiler
📊 A fast and simple library to passively profile JS/Hermes performance in production and release builds.
https://github.com/margelo/react-native-release-profiler
debug debugger hermes jsi perf performance production profiler profiling release sample trace
Last synced: 5 months ago
JSON representation
📊 A fast and simple library to passively profile JS/Hermes performance in production and release builds.
- Host: GitHub
- URL: https://github.com/margelo/react-native-release-profiler
- Owner: margelo
- License: mit
- Created: 2023-11-30T18:00:11.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-08T15:34:53.000Z (6 months ago)
- Last Synced: 2025-05-08T12:15:07.556Z (5 months ago)
- Topics: debug, debugger, hermes, jsi, perf, performance, production, profiler, profiling, release, sample, trace
- Language: JavaScript
- Homepage: https://margelo.io
- Size: 2.26 MB
- Stars: 246
- Watchers: 8
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# react-native-release-profiler
A fast and simple library to passively profile JS/Hermes performance in production and release builds.
## Why
Usually performance issues are profiled in debug builds, which could lead to false positives (e.g. JS Garbage Collectors, Hermes-specific debug markers, or other LLDB hangs).
**react-native-release-profiler** allows you to profile your app in release builds, both in a local environment to profile specific issues, as well as in a production environment to spot regressions or collect performance samples from a wider variety of user devices.
## Web support
The web support is based on sampling [JS Self-Profiling](https://wicg.github.io/js-self-profiling/) API, so not all browsers support it yet. To see in which browsers it is supported, check [this page](https://caniuse.com/mdn-api_profiler).
To make it possible to work you'll need to add `'Document-Policy': 'js-profiling'` header to your server response. Using `webpack` in dev mode you can do that by adding these lines to your `webpack.config.js`:
```js
devServer: {
headers: {
'Document-Policy': 'js-profiling',
},
}
```
> [!WARNING]
> By default sampling interval is set to 10 milliseconds. This is the lowest supported interval, but on Windows machines this interval will be 16 milliseconds.
## Need help?
If you're having performance problems in your app, feel free to reach out to us at hello@margelo.io. We do this a lot. 😉
## Installation
```sh
yarn add react-native-release-profiler
cd ios && pod install
```
### Expo
Expo requires you to also install @react-native-community/cli
```sh
yarn add --dev @react-native-community/cli
```
## Usage
1. Install **react-native-release-profiler**
2. Build your app in release mode
3. Start a profiling session:
```ts
import { startProfiling } from 'react-native-release-profiler'
startProfiling()
```
4. Stop the profiling session:
```ts
import { stopProfiling } from 'react-native-release-profiler'
// `true` to save the trace to the phone's downloads folder, `false` otherwise
const path = await stopProfiling(true)
```
5. Download and process the performance trace from your phone to your PC:
- On **Android**:
```
npx react-native-release-profiler --fromDownload --appId
```
- On **iOS** and **web**:
```
npx react-native-release-profiler --local
```
6. Open the performance trace in your tool of choice:
- SpeedScope (https://www.speedscope.app)
- Perfetto UI (https://ui.perfetto.dev/)
- Google Chrome's Tracing UI ([chrome://tracing](chrome://tracing))
## API
### `startProfiling(): void`
Synchronously starts the Hermes Profiling Session.
### `stopProfiling(saveInDownloadsDirectory?: boolean, fileName?: string): Promise`
Asynchronously stops the Hermes Profiling Session, and saves the file in a cache or downloads directory if `saveInDownloadsDirectory` is `true` using the provided `fileName` (web only).
Returns the path of the saved profile.
## Contributing
See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
## License
MIT