Skip to content

Commit e99cf63

Browse files
j-piaseckij-piasecki
authored
Add LLM skill for migration to RNGH3 (#3947)
## Description Adds a skill to make llms able to migrate the code to RNGH3 ## Test plan Try to migrate some old examples using an agent
1 parent d95aa05 commit e99cf63

File tree

1 file changed

+167
-0
lines changed
  • skills/gesture-handler-3-migration

1 file changed

+167
-0
lines changed

‎skills/gesture-handler-3-migration/SKILL.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
name: gesture-handler-3-migration
3+
description: Migrates files containing React Native components which use the React Native Gesture Handler 2 API to Gesture Handler 3.
4+
---
5+
6+
# Migrate to Gesture Handler 3
7+
8+
This skill scans React Native components that use the Gesture Handler builder-based API and updates them to use the new hook-based API. It also updates related types and components to adapt to the new version.
9+
10+
## When to Use
11+
12+
- Updating the usage of components imported from `react-native-gesture-handler`
13+
- Upgrading to Gesture Handler 3
14+
- Migrating to the new hook-based gesture API
15+
16+
## Instructions
17+
18+
Use the instructions below to correctly replace all legacy APIs with the modern ones.
19+
20+
1. Identify all imports from 'react-native-gesture-handler'
21+
2. For each `Gesture.X()` call, replace with corresponding `useXGesture()` hook
22+
3. Replace `Gesture` import with imports for the used hooks
23+
4. Convert builder method chains to configuration objects
24+
5. Update callback names (onStart → onActivate, etc.)
25+
6. Replace composed gestures with relation hooks. Keep rules of hooks in mind
26+
7. Update GestureDetector usage if SVG is involved to Intercepting/Virtual GestureDetector
27+
8. Update usage of compoenent imported from 'react-native-gesture-handler' according to "Legacy components" section
28+
29+
### Migrating gestures
30+
31+
All hook gestures have their counterparts in the builder API: `Gesture.X()` becomes `useXGesture(config)`. The methods are now config object fields with the same name as the relevant builder methods, unless specified otherwise.
32+
33+
The exception to thait is `Gesture.ForceTouch` which DOES NOT have a counterpart in the hook API.
34+
35+
#### Callback changes
36+
37+
In Gesture Handler 3 some of the callbacks were renamed, namely:
38+
- `onStart` -> `onActivate`
39+
- `onEnd` -> `onDeactivate`
40+
- `onTouchesCancelled` -> `onTouchesCancel`
41+
42+
In the hooks API `onChange` is no longer available. Instead the `*change*` properties were moved to the event available inside `onUpdate`.
43+
44+
All callbacks of a gesture are now using the same type:
45+
- `usePanGesture()` -> `PanGestureEvent`
46+
- `useTapGesture()` -> `TapGestureEvent`
47+
- `useLongPressGesture()` -> `LongPressGestureEvent`
48+
- `useRotationGesture()` -> `RotationGestureEvent`
49+
- `usePinchGesture()` -> `PinchGestureEvent`
50+
- `useFlingGesture()` -> `FlingGestureEvent`
51+
- `useHoverGesture()` -> `HoverGestureEvent`
52+
- `useNativeGesture()` -> `RotationGestureEvent`
53+
- `useManualGesture()` -> `ManualGestureEvent`
54+
55+
The exception to this is touch events:
56+
- `onTouchesDown`
57+
- `onTouchesUp`
58+
- `onTouchesMove`
59+
- `onTouchesCancel`
60+
61+
Where each callback receives `GestureTouchEvent` regardless of the hook used.
62+
63+
#### StateManager
64+
65+
In Gesture Handler 3, `stateManager` is no longer passed to `TouchEvent` callbacks. Instead, you should use the global `GestureStateManager`.
66+
67+
`GestureStateManager` provides methods for imperative state management:
68+
- .begin(handlerTag: number)
69+
- .activate(handlerTag: number)
70+
- .deactivate(handlerTag: number) (.end() in the old API)
71+
- .fail(handlerTag: number)
72+
73+
`handlerTag` can be obtained in two ways:
74+
1. From the gesture object returned by the hook (`gesture.handlerTag`)
75+
2. From the event inside callback (`event.handlerTag`)
76+
77+
Callback definitions CANNOT reference the gesture that's being defined. In this scenario use events to get access to the handler tag.
78+
79+
### Migrating relations
80+
81+
#### Composed gestures
82+
83+
`Gesture.Simultaneous(gesture1, gesture2);` becomes `useSimultaneousGestures(pan1, pan2);`
84+
85+
All relations from the old API and their counterparts in the new one:
86+
- `Gesture.Race()` -> `useCompetingGestures()`
87+
- `Gesture.Simultaneous()` -> `useSimultaneousGestures()`
88+
- `Gesture.Exclusive()` -> `useExclusiveGestures()`
89+
90+
#### Cross components relations properties
91+
92+
Properties used to define cross-components interactions were renamed:
93+
- `.simultaneousWithExternalGesture` -> `simultaneousWith:`
94+
- `.requireExternalGestureToFail` -> `requireToFail:`
95+
- `.blocksExternalGesture` -> `block:`
96+
97+
### GestureDetector
98+
99+
The `GestureDetector` is a key component of `react-native-gesture-handler`. It supports gestures created either using the hooks API or the builder pattern (but those cannot be mixed, it's either or).
100+
101+
Don't use the same instance of a gesture across multiple Gesture Detectors as it will lead to an undefined behavior.
102+
103+
### Integration with Reanimated
104+
105+
Worklets' Babel plugin is setup in a way that automatically marks callbacks passed to gestures in the configuration chain as worklets. This means that you don't need to add a `'worklet';` directive at the beginning of the functions.
106+
107+
This will not be workletized because the callback is defined outside of the gesture object:
108+
109+
```jsx
110+
const callback = () => {
111+
console.log(_WORKLET);
112+
};
113+
114+
const gesture = useTapGesture({
115+
onBegin: callback,
116+
});
117+
```
118+
119+
The callback wrapped by any other higher order function will not be workletized:
120+
121+
```jsx
122+
const gesture = useTapGesture({
123+
onBegin: useCallback(() => {
124+
console.log(_WORKLET);
125+
}, []),
126+
});
127+
```
128+
129+
In the above cases, you should add a `"worklet";` directive as the first line of the callback.
130+
131+
### Disabling Reanimated
132+
133+
Gestures created with the hook API have `Reanimated` integration enabled by default (if it's installed), meaning all callbacks are executed on the UI thread.
134+
135+
#### runOnJS
136+
137+
The `runOnJS` property allows you to dynamically control whether callbacks are executed on the JS thread or the UI thread. When set to `true`, callbacks will run on the JS thread. Setting it to `false` will execute them on the UI thread. Default value is `false`.
138+
139+
### Migrating components relying on view hierarchy
140+
141+
Certain components, such as `SVG`, depend on the view hierarchy to function correctly. In Gesture Handler 3, `GestureDetector` disrupts these hierarchies. To resolve this issue, two new detectors have been introduced: `InterceptingGestureDetector` and `VirtualGestureDetector`.
142+
143+
`InterceptingGestureDetector` functions similarly to the `GestureDetector`, but it can also act as a proxy for `VirtualGestureDetector` within its component subtree. Because it can be used solely to establish the context for virtual detectors, the `gesture` property is optional.
144+
145+
`VirtualGestureDetector` is similar to the `GestureDetector` from RNGH2. Because it is not a host component, it does not interfere with the host view hierarchy. This allows you to attach gestures without disrupting functionality that depends on it.
146+
147+
**Warning:** `VirtualGestureDetector` has to be a descendant of `InterceptingGestureDetector`.
148+
149+
#### Migrating SVG
150+
151+
In Gesture Handler 2 it was possible to use `GestureDetector` directly on `SVG`. In Gesture Handler 3, the correct way to interact with `SVG` is to use `InterceptingGestureDetector` and `VirtualGestureDetector`.
152+
153+
### Legacy components
154+
155+
When the code using the component relies on the APIs that are no longer available on the components in Gesture Handler 3 (like `waitFor`, `simultaneousWith`, `blocksHandler`, `onHandlerStateChange`, `onGestureEvent` props), it cannot be easily migrated in isolation. In this case update the imports to the Legacy version of the component, and inform the user that the dependencies need to be migrated first.
156+
157+
If the migration is possible, use the ask questions tool to clarify the user intent unless clearly stated beforehand: should the components be using the new implementation (no `Legacy` prefix when imported), or should they revert to the old implementation (`Legacy` prefix when imported)?
158+
159+
Don't suggest replacing buttons from Gesture Handler with components from React Native and vice versa.
160+
161+
The implementation of buttons has been updated, resolving most button-related issues. They have also been internally rewritten to utilize the new hook API. The legacy JS implementations of button components are still accessible but have been renamed with the prefix `Legacy`, e.g., `RectButton` is now available as `LegacyRectButton`. Those still use the new native component under the hood.
162+
163+
Other components have also been internally rewritten using the new hook API but are exported under their original names, so no changes are necessary on your part. However, if you need to use the previous implementation for any reason, the legacy components are also available and are prefixed with `Legacy`, e.g., `ScrollView` is now available as `LegacyScrollView`.
164+
165+
### Replaced types
166+
167+
Most of the types used in the builder API, like `TapGesture`, are still present in Gesture Handler 3. However, they are now used in new hook API. Types for builder API now have `Legacy` prefix, e.g. `TapGesture` becomes `LegacyTapGesture`.

0 commit comments

Comments
 (0)