0
# Jetifier
1

2
Jetifier is the AndroidX transition tool in npm package format, designed specifically for React Native projects. It automatically converts Android Support Library dependencies to AndroidX equivalents and vice versa by performing source code transformations on node_modules dependencies.
3

4
> **⚠️ Deprecation Notice**: Jetifier is deprecated. Future versions of React Native CLI may not run it by default.
5

6
## Package Information
7

8
- **Package Name**: jetifier
9
- **Package Type**: npm
10
- **Language**: JavaScript (Node.js)
11
- **Installation**: `npm install --save-dev jetifier`
12
- **Global Installation**: `npm install -g jetifier`
13

14
## Core Imports
15

16
For programmatic access to utility functions:
17

18
```javascript
19
const { getClassesMapping, readDir, chunk } = require('jetifier/src/utils');
20
```
21

22
Note: Jetifier is primarily designed as a command-line tool rather than a programmatic API.
23

24
## Basic Usage
25

26
### Forward Jetification (Support Library → AndroidX)
27

28
Convert Android Support Library dependencies to AndroidX (default mode):
29

30
```bash
31
# Install as dev dependency
32
npm install --save-dev jetifier
33

34
# Run jetifier to convert Support Library to AndroidX
35
npx jetify
36

37
# Or use the alias
38
npx jetifier
39
```
40

41
### Reverse Jetification (AndroidX → Support Library)
42

43
Convert AndroidX dependencies back to Android Support Library:
44

45
```bash
46
# Run in reverse mode
47
npx jetify reverse
48

49
# Or use the short flag
50
npx jetify -r
51
```
52

53
### Automatic Integration
54

55
For React Native 0.60+, jetifier runs automatically with the React Native CLI. For manual integration, add to package.json:
56

57
```json
58
{
59
  "scripts": {
60
    "postinstall": "npx jetify"
61
  }
62
}
63
```
64

65
## Architecture
66

67
Jetifier uses a multi-worker architecture for efficient processing:
68

69
- **Main Process**: Orchestrates file discovery and worker distribution
70
- **Worker Processes**: Perform actual file transformations in parallel
71
- **File Discovery**: Recursively scans node_modules for transformable files (.java, .xml, .kt)
72
- **Class Mapping**: Uses AndroidX official class mapping data with custom additions
73
- **Multi-core Processing**: Utilizes all available CPU cores for maximum performance
74

75
## Capabilities
76

77
### Command Line Interface
78

79
Primary interface for running jetifier transformations.
80

81
```bash { .api }
82
# Forward jetification (default)
83
npx jetify
84

85
# Reverse jetification  
86
npx jetify reverse
87
npx jetify -r
88

89
# Standalone JAR/AAR/ZIP processing
90
npx jetifier-standalone [options] <input> <output>
91
npx jetifier-standalone -h  # Show help
92
```
93

94
**Supported File Types:**
95
- `.java` - Java source files
96
- `.xml` - Android XML files  
97
- `.kt` - Kotlin source files
98

99
**Processing Modes:**
100
- `forward` (default): Convert Support Library → AndroidX
101
- `reverse`: Convert AndroidX → Support Library
102

103
### Utility Functions
104

105
Internal utility functions available for programmatic access.
106

107
```javascript { .api }
108
/**
109
 * Load and process AndroidX class mapping data from CSV file
110
 * @returns {Array<Array<string>>} Array of [oldClass, newClass] mapping pairs
111
 */
112
function getClassesMapping();
113

114
/**
115
 * Recursively read directory to find Java, Kotlin, and XML files
116
 * @param {string} dir - Directory path to scan recursively
117
 * @param {Array<string>} filesList - Optional array to accumulate file paths (default: [])
118
 * @returns {Array<string>} Array of file paths with .java, .xml, or .kt extensions
119
 */
120
function readDir(dir, filesList = []);
121

122
/**
123
 * Split array into approximately equal chunks for worker distribution
124
 * @param {Array} array - Array to split into chunks
125
 * @param {number} chunkSize - Number of chunks to create (typically CPU count)
126
 * @returns {Array<Array>} Array of arrays where each sub-array is a chunk
127
 */
128
function chunk(array, chunkSize);
129
```
130

131
### File Processing Engine
132

133
Core transformation engine that processes files using class mappings.
134

135
```javascript { .api }
136
/**
137
 * Worker process message interface
138
 * @interface WorkerMessage
139
 */
140
interface WorkerMessage {
141
  /** Chunk of files to process */
142
  filesChunk: string[];
143
  /** Class mapping pairs for transformation */
144
  classesMapping: Array<[string, string]>;
145
  /** Processing mode: 'forward' or 'reverse' */
146
  mode: 'forward' | 'reverse';
147
}
148
```
149

150
**Processing Strategy:**
151
- Files are distributed across multiple worker processes
152
- Each worker processes its assigned file chunk independently
153
- Class mappings are sorted by length (longest first) to avoid substring conflicts
154
- Global regex replacement ensures complete transformation
155
- Files are modified in-place
156

157
### Standalone JAR Processing
158

159
Java-based jetifier for processing JAR/AAR/ZIP files directly.
160

161
```bash { .api }
162
# Process individual files
163
jetifier-standalone input.aar output.aar
164

165
# Common options
166
jetifier-standalone -h                    # Show help
167
jetifier-standalone -v                    # Verbose output
168
jetifier-standalone -r input.aar output.aar  # Reverse mode
169
```
170

171
**Supported Archive Types:**
172
- `.jar` - Java Archive files
173
- `.aar` - Android Archive files  
174
- `.zip` - ZIP archives containing Android code
175

176
## Configuration
177

178
### Class Mapping Data
179

180
Jetifier uses the official AndroidX class mapping with custom additions:
181

182
```csv
183
Support Library class,Android X class
184
android.support.v4.app.Fragment,androidx.fragment.app.Fragment
185
android.support.v7.app.AppCompatActivity,androidx.appcompat.app.AppCompatActivity
186
```
187

188
**Custom Mappings:**
189
- `android.support.v8.renderscript` → `android.renderscript`
190

191
### Environment Variables
192

193
```bash { .api }
194
# No specific environment variables required
195
# Jetifier automatically detects node_modules directory
196
```
197

198
### File Selection Criteria
199

200
```javascript { .api }
201
/**
202
 * File filtering criteria
203
 */
204
const FILE_EXTENSIONS = ['.java', '.xml', '.kt'];
205
const SEARCH_DIRECTORY = 'node_modules';
206
const SKIP_SYMBOLIC_LINKS = true;
207
```
208

209
## Error Handling
210

211
### Common Issues and Solutions
212

213
**Wildcard Import Issues:**
214
```java
215
// Problematic - will not convert properly
216
import android.support.v4.content.*;
217

218
// Solution - use concrete imports
219
import android.support.v4.content.ContextCompat;
220
import android.support.v4.content.FileProvider;
221
```
222

223
**Duplicate AndroidManifest.xml:**
224
- Some libraries violate Android packaging rules
225
- Results in dex merger errors
226
- Solution: Open PRs with library maintainers
227

228
**CompileSdk Version Conflicts:**
229
- Libraries that don't allow compileSdk override
230
- Prevents setting compileSdk to 28+ as required by AndroidX
231
- Solution: Use version overrides in build.gradle
232

233
### Troubleshooting Commands
234

235
```bash { .api }
236
# Verify node_modules structure
237
ls -la node_modules/
238

239
# Check for symbolic links (skipped by jetifier)
240
find node_modules/ -type l
241

242
# Manually verify transformations
243
grep -r "android.support" node_modules/ --include="*.java"
244
grep -r "androidx" node_modules/ --include="*.java"
245
```
246

247
## Integration Examples
248

249
### React Native Project Setup
250

251
```json
252
{
253
  "name": "my-rn-app",
254
  "devDependencies": {
255
    "jetifier": "^2.0.0"
256
  },
257
  "scripts": {
258
    "postinstall": "npx jetify",
259
    "android": "npx jetify && npx react-native run-android"
260
  }
261
}
262
```
263

264
### Library Maintainer Support
265

266
For library authors supporting both AndroidX and pre-AndroidX users:
267

268
```gradle
269
android {
270
    compileSdkVersion project.hasProperty('compileSdkVersion') ? project.compileSdkVersion : 28
271
    
272
    dependencies {
273
        def support_version = project.hasProperty('supportLibVersion') ? project.supportLibVersion : '28.0.0'
274
        def appcompat_lib = project.hasProperty('appCompatLib') ? project.appCompatLib : 'com.android.support:appcompat-v7'
275
        
276
        implementation "${appcompat_lib}:${support_version}"
277
    }
278
}
279
```
280

281
### CI/CD Integration
282

283
```yaml
284
# GitHub Actions example
285
- name: Install dependencies
286
  run: npm install
287

288
- name: Run jetifier
289
  run: npx jetify
290

291
- name: Build Android
292
  run: npx react-native run-android --variant=release
293
```
294

295
## Types
296

297
```javascript { .api }
298
/**
299
 * Processing mode constants
300
 * @type {string} Either 'forward' or 'reverse'
301
 */
302
const ProcessingMode = 'forward' | 'reverse';
303

304
/**
305
 * Class mapping array structure
306
 * @type {Array<string>} Two-element array: [oldClassName, newClassName]
307
 */
308
const ClassMapping = [string, string];
309

310
/**
311
 * Worker message object structure sent to child processes
312
 * @typedef {Object} WorkerMessage
313
 * @property {Array<string>} filesChunk - Array of file paths to process
314
 * @property {Array<Array<string>>} classesMapping - Array of [oldClass, newClass] pairs
315
 * @property {string} mode - Processing mode: 'forward' or 'reverse'
316
 */
317
```