or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-jetifier

AndroidX transition tool for React Native that converts between Android Support Library and AndroidX dependencies

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/jetifier@2.0.x

To install, run

npx @tessl/cli install tessl/npm-jetifier@2.0.0

Jetifier

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.

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

Package Information

Package Name: jetifier
Package Type: npm
Language: JavaScript (Node.js)
Installation: npm install --save-dev jetifier
Global Installation: npm install -g jetifier

Core Imports

For programmatic access to utility functions:

const { getClassesMapping, readDir, chunk } = require('jetifier/src/utils');

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

Basic Usage

Forward Jetification (Support Library → AndroidX)

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

# Install as dev dependency
npm install --save-dev jetifier

# Run jetifier to convert Support Library to AndroidX
npx jetify

# Or use the alias
npx jetifier

Reverse Jetification (AndroidX → Support Library)

Convert AndroidX dependencies back to Android Support Library:

# Run in reverse mode
npx jetify reverse

# Or use the short flag
npx jetify -r

Automatic Integration

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

{
  "scripts": {
    "postinstall": "npx jetify"
  }
}

Architecture

Jetifier uses a multi-worker architecture for efficient processing:

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

Capabilities

Command Line Interface

Primary interface for running jetifier transformations.

# Forward jetification (default)
npx jetify

# Reverse jetification  
npx jetify reverse
npx jetify -r

# Standalone JAR/AAR/ZIP processing
npx jetifier-standalone [options] <input> <output>
npx jetifier-standalone -h  # Show help

Supported File Types:

.java - Java source files
.xml - Android XML files
.kt - Kotlin source files

Processing Modes:

forward (default): Convert Support Library → AndroidX
reverse: Convert AndroidX → Support Library

Utility Functions

Internal utility functions available for programmatic access.

/**
 * Load and process AndroidX class mapping data from CSV file
 * @returns {Array<Array<string>>} Array of [oldClass, newClass] mapping pairs
 */
function getClassesMapping();

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

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

File Processing Engine

Core transformation engine that processes files using class mappings.

/**
 * Worker process message interface
 * @interface WorkerMessage
 */
interface WorkerMessage {
  /** Chunk of files to process */
  filesChunk: string[];
  /** Class mapping pairs for transformation */
  classesMapping: Array<[string, string]>;
  /** Processing mode: 'forward' or 'reverse' */
  mode: 'forward' | 'reverse';
}

Processing Strategy:

Files are distributed across multiple worker processes
Each worker processes its assigned file chunk independently
Class mappings are sorted by length (longest first) to avoid substring conflicts
Global regex replacement ensures complete transformation
Files are modified in-place

Standalone JAR Processing

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

# Process individual files
jetifier-standalone input.aar output.aar

# Common options
jetifier-standalone -h                    # Show help
jetifier-standalone -v                    # Verbose output
jetifier-standalone -r input.aar output.aar  # Reverse mode

Supported Archive Types:

.jar - Java Archive files
.aar - Android Archive files
.zip - ZIP archives containing Android code

Configuration

Class Mapping Data

Jetifier uses the official AndroidX class mapping with custom additions:

Support Library class,Android X class
android.support.v4.app.Fragment,androidx.fragment.app.Fragment
android.support.v7.app.AppCompatActivity,androidx.appcompat.app.AppCompatActivity

Custom Mappings:

android.support.v8.renderscript → android.renderscript

Environment Variables

# No specific environment variables required
# Jetifier automatically detects node_modules directory

File Selection Criteria

/**
 * File filtering criteria
 */
const FILE_EXTENSIONS = ['.java', '.xml', '.kt'];
const SEARCH_DIRECTORY = 'node_modules';
const SKIP_SYMBOLIC_LINKS = true;

Error Handling

Common Issues and Solutions

Wildcard Import Issues:

// Problematic - will not convert properly
import android.support.v4.content.*;

// Solution - use concrete imports
import android.support.v4.content.ContextCompat;
import android.support.v4.content.FileProvider;

Duplicate AndroidManifest.xml:

Some libraries violate Android packaging rules
Results in dex merger errors
Solution: Open PRs with library maintainers

CompileSdk Version Conflicts:

Libraries that don't allow compileSdk override
Prevents setting compileSdk to 28+ as required by AndroidX
Solution: Use version overrides in build.gradle

Troubleshooting Commands

# Verify node_modules structure
ls -la node_modules/

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

# Manually verify transformations
grep -r "android.support" node_modules/ --include="*.java"
grep -r "androidx" node_modules/ --include="*.java"

Integration Examples

React Native Project Setup

{
  "name": "my-rn-app",
  "devDependencies": {
    "jetifier": "^2.0.0"
  },
  "scripts": {
    "postinstall": "npx jetify",
    "android": "npx jetify && npx react-native run-android"
  }
}

Library Maintainer Support

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

android {
    compileSdkVersion project.hasProperty('compileSdkVersion') ? project.compileSdkVersion : 28
    
    dependencies {
        def support_version = project.hasProperty('supportLibVersion') ? project.supportLibVersion : '28.0.0'
        def appcompat_lib = project.hasProperty('appCompatLib') ? project.appCompatLib : 'com.android.support:appcompat-v7'
        
        implementation "${appcompat_lib}:${support_version}"
    }
}

CI/CD Integration

# GitHub Actions example
- name: Install dependencies
  run: npm install

- name: Run jetifier
  run: npx jetify

- name: Build Android
  run: npx react-native run-android --variant=release

Types

/**
 * Processing mode constants
 * @type {string} Either 'forward' or 'reverse'
 */
const ProcessingMode = 'forward' | 'reverse';

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

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