Skip to content

Commit d4fcb93

Browse files
hramoshramos
authored
The Hermes docs in next, also apply to 0.70. (facebook#3380)
1 parent 0339cae commit d4fcb93

File tree

1 file changed

+103
-59
lines changed

1 file changed

+103
-59
lines changed

‎website/versioned_docs/version-0.70/hermes.md

Lines changed: 103 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,78 @@ import M1Cocoapods from './\_markdown-m1-cocoapods.mdx';
99
<img width={300} height={300} className="hermes-logo" src="/docs/assets/HermesLogo.svg" />
1010
</a>
1111

12-
[Hermes](https://hermesengine.dev) is an open-source JavaScript engine optimized for React Native. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an **opt-in** React Native feature, and this guide explains how to enable it.
12+
[Hermes](https://hermesengine.dev) is an open-source JavaScript engine optimized for React Native. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size.
13+
As of React Native 0.70, Hermes is the default engine and no additional configuration is required to enable it.
1314

14-
First, ensure you're using at least version 0.60.4 of React Native.
15+
## Bundled Hermes
16+
17+
Starting with React Native 0.69.0, every version of React Native will come with a **bundled version** of Hermes.
18+
We will be building a version of Hermes for you whenever we release a new version of React Native. This will make sure you're consuming a version of Hermes which is fully compatible with the version of React Native you're using.
19+
20+
Historically, we had problems with matching versions of Hermes with versions of React Native. This fully eliminates this problem, and offers users a JS engine that is compatible with the specific React Native version.
21+
22+
This change is fully transparent to users of React Native. You can still enable/disable Hermes using the command described in this page.
23+
You can [read more about the technical implementation on this page](/architecture/bundled-hermes).
24+
25+
## Confirming Hermes is in use
26+
27+
If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:
28+
29+
![Where to find JS engine status in AwesomeProject](/docs/assets/HermesApp.jpg)
30+
31+
A `HermesInternal` global variable will be available in JavaScript that can be used to verify that Hermes is in use:
32+
33+
```jsx
34+
const isHermes = () => !!global.HermesInternal;
35+
```
36+
37+
:::caution
38+
If you are using a non-standard way of loading the JS bundle, it is possible that the `HermesInternal` variable is available but you aren't using the highly optimised pre-compiled bytecode.
39+
Confirm that you are using the `.hbc` file and also benchmark the before/after as detailed below.
40+
:::
41+
42+
To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:
43+
44+
```shell
45+
$ npx react-native run-android --variant release
46+
```
47+
48+
or for iOS:
49+
50+
```shell
51+
$ npx react-native run-ios --configuration Release
52+
```
53+
54+
This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.
55+
56+
## Debugging JS on Hermes using Google Chrome's DevTools
57+
58+
Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a real, physical, device.
59+
60+
:::info
61+
Note that this is very different with the "Remote JS Debugging" from the In-App Developer Menu documented in the [Debugging](debugging#debugging-using-a-custom-javascript-debugger) section, which actually runs the JS code on Chrome's V8 on your development machine (laptop or desktop).
62+
:::
63+
64+
Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on `localhost:8081`, but this is [configurable](https://facebook.github.io/metro/docs/configuration). When running `yarn start` the address is written to stdout on startup.
65+
66+
Once you know where the Metro server is listening, you can connect with Chrome using the following steps:
67+
68+
1. Navigate to `chrome://inspect` in a Chrome browser instance.
69+
70+
2. Use the `Configure...` button to add the Metro server address (typically `localhost:8081` as described above).
71+
72+
![Configure button in Chrome DevTools devices page](/docs/assets/HermesDebugChromeConfig.png)
73+
74+
![Dialog for adding Chrome DevTools network targets](/docs/assets/HermesDebugChromeMetroAddress.png)
75+
76+
3. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. ![Target inspect link](/docs/assets/HermesDebugChromeInspect.png)
77+
78+
4. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. ![Pause button in debug tools](/docs/assets/HermesDebugChromePause.png)
79+
80+
## Enabling Hermes on Older Versions of React Native
81+
82+
Hermes is the default engine as of React Native 0.70. This section explains how to enable Hermes on older versions of React Native.
83+
First, ensure you're using at least version 0.60.4 of React Native to enable Hermes on Android or 0.64 of React Native to enable Hermes on iOS.
1584

1685
If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See [Upgrading to new React Native Versions](/docs/upgrading) for how to do this. After upgrading the app, make sure everything works before trying to switch to Hermes.
1786

@@ -24,8 +93,6 @@ Version mismatch can result in instant crash of your apps in the worst case scen
2493
Hermes requires [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=48145).
2594
:::
2695

27-
## Enabling Hermes
28-
2996
### Android
3097

3198
Edit your `android/app/build.gradle` file and make the change illustrated below:
@@ -36,6 +103,18 @@ Edit your `android/app/build.gradle` file and make the change illustrated below:
36103
- enableHermes: false // clean and rebuild if changing
37104
+ enableHermes: true // clean and rebuild if changing
38105
]
106+
107+
// ...
108+
109+
if (enableHermes) {
110+
- def hermesPath = "../../node_modules/hermes-engine/android/";
111+
- debugImplementation files(hermesPath + "hermes-debug.aar")
112+
- releaseImplementation files(hermesPath + "hermes-release.aar")
113+
+ //noinspection GradleDynamicVersion
114+
+ implementation("com.facebook.react:hermes-engine:+") { // From node_modules
115+
+ exclude group:'com.facebook.fbjni'
116+
+ }
117+
} else {
39118
```
40119

41120
Also, if you're using ProGuard, you will need to add these rules in `proguard-rules.pro` :
@@ -93,67 +172,32 @@ That's it! You should now be able to develop and deploy your app as usual:
93172
$ npx react-native run-ios
94173
```
95174

96-
## Confirming Hermes is in use
175+
## Switching back to JavaScriptCore
97176

98-
If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:
177+
React Native also supports using JavaScriptCore as the JS engine. Follow these instructions to opt-out of Hermes.
99178

100-
![Where to find JS engine status in AwesomeProject](/docs/assets/HermesApp.jpg)
179+
### Android
101180

102-
A `HermesInternal` global variable will be available in JavaScript that can be used to verify that Hermes is in use:
181+
Edit your `android/app/build.gradle` file and make the change illustrated below:
103182

104-
```jsx
105-
const isHermes = () => !!global.HermesInternal;
183+
```diff
184+
project.ext.react = [
185+
- enableHermes: true, // clean and rebuild if changing
186+
+ enableHermes: false, // clean and rebuild if changing
187+
]
106188
```
107189

108-
:::caution
109-
If you are using a non-standard way of loading the JS bundle, it is possible that the `HermesInternal` variable is available but you aren't using the highly optimised pre-compiled bytecode.
110-
Confirm that you are using the `.hbc` file and also benchmark the before/after as detailed below.
111-
:::
112-
113-
To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:
114-
115-
```shell
116-
$ npx react-native run-android --variant release
117-
```
190+
### iOS
118191

119-
or for iOS:
192+
Edit your `ios/Podfile` file and make the change illustrated below:
120193

121-
```shell
122-
$ npx react-native run-ios --configuration Release
194+
```diff
195+
use_react_native!(
196+
:path => config[:reactNativePath],
197+
# Hermes is now enabled by default. Disable by setting this flag to false.
198+
# Upcoming versions of React Native may rely on get_default_flags(), but
199+
# we make it explicit here to aid in the React Native upgrade process.
200+
- :hermes_enabled => flags[:hermes_enabled],
201+
+ :hermes_enabled => false,
202+
)
123203
```
124-
125-
This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.
126-
127-
## Bundled Hermes
128-
129-
Starting with React Native 0.69.0, every version of React Native will come with a **bundled version** of Hermes.
130-
We will be building a version of Hermes for you whenever we release a new version of React Native. This will make sure you're consuming a version of Hermes which is fully compatible with the version of React Native you're using.
131-
132-
Historically, we had problems with matching versions of Hermes with versions of React Native. This fully eliminates this problem, and offers users a JS engine that is compatible with the specific React Native version.
133-
134-
This change is fully transparent to users of React Native. You can still enable/disable Hermes using the command described in this page.
135-
You can [read more about the technical implementation on this page](/architecture/bundled-hermes).
136-
137-
## Debugging JS on Hermes using Google Chrome's DevTools
138-
139-
Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a real, physical, device.
140-
141-
:::info
142-
Note that this is very different with the "Remote JS Debugging" from the In-App Developer Menu documented in the [Debugging](debugging#debugging-using-a-custom-javascript-debugger) section, which actually runs the JS code on Chrome's V8 on your development machine (laptop or desktop).
143-
:::
144-
145-
Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on `localhost:8081`, but this is [configurable](https://facebook.github.io/metro/docs/configuration). When running `yarn start` the address is written to stdout on startup.
146-
147-
Once you know where the Metro server is listening, you can connect with Chrome using the following steps:
148-
149-
1. Navigate to `chrome://inspect` in a Chrome browser instance.
150-
151-
2. Use the `Configure...` button to add the Metro server address (typically `localhost:8081` as described above).
152-
153-
![Configure button in Chrome DevTools devices page](/docs/assets/HermesDebugChromeConfig.png)
154-
155-
![Dialog for adding Chrome DevTools network targets](/docs/assets/HermesDebugChromeMetroAddress.png)
156-
157-
3. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. ![Target inspect link](/docs/assets/HermesDebugChromeInspect.png)
158-
159-
4. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. ![Pause button in debug tools](/docs/assets/HermesDebugChromePause.png)

0 commit comments

Comments
 (0)