rn-16kb-support

A CLI tool and library to detect Android native artifacts that may not support 16KB Memory Page Size in React Native projects.

Overview

Android 15 introduces support for 16KB memory page sizes, which can improve app performance but requires native libraries to be compatible. This tool helps identify potential compatibility issues in your React Native project's native dependencies.

Installation

npm install -g rn-16kb-support
# or run directly with npx
npx rn-16kb-support

Usage

CLI

npx rn-16kb-check [options] [path]

Options

• --path <projectRoot>: Project root directory (default: current working directory)
• --format <text|json>: Output format (default: text)
• --verbose: Show extra information
• --fail-on-issue: Exit with code 1 if any incompatibility found
• --detectors <list>: Comma separated detectors to run (default: 'default')

Examples

# Scan current directory with text output
npx rn-16kb-check

# Scan specific project with verbose output
npx rn-16kb-check --path ./my-react-native-app --verbose

# Get JSON output for CI integration
npx rn-16kb-check --format json

# Fail CI build if issues found
npx rn-16kb-check --fail-on-issue

Sample Output

Text format:

Scanning project /path/to/my-app
Found 42 native artifacts, running 1 detectors

✖ warning: potential incompatibility found
- package: react-native-foo
  path: node_modules/react-native-foo/android/libs/libfoo.so
  artifact: so
  detector: default
  reason: "ELF program header alignment suggests built with 4KB assumption (alignment: 0x1000)"
  docs: https://github.com/kbqdev/rn-16kb-support#how-to-fix

✔ pass: react-native-bar (node_modules/react-native-bar/android/library.aar)

JSON format:

[
  {
    "package": "react-native-foo",
    "path": "node_modules/react-native-foo/android/libs/libfoo.so",
    "artifact": "so",
    "detections": [
      {
        "name": "default",
        "ok": false,
        "score": 78,
        "reason": "ELF program header alignment suggests built with 4KB assumption (alignment: 0x1000)"
      }
    ]
  }
]

API

scanProject(projectRoot, options)

Scan a project for 16KB page size compatibility issues.

import { scanProject } from 'rn-16kb-support';

const results = await scanProject('/path/to/project', {
  projectRoot: '/path/to/project',
  detectors: ['default'],
  verbose: true
});

runCli(args)

Run the CLI programmatically.

import { runCli } from 'rn-16kb-support';

await runCli(['--path', '/my/project', '--format', 'json']);

Detectors

The tool uses pluggable detectors to analyze different types of artifacts:

Default Detector

The default detector analyzes:

• .so files: Uses readelf if available, falls back to manual ELF header parsing
• .aar files: Extracts and analyzes embedded .so files
• .jar files: Currently returns OK (no native code expected)

Detection Heuristics

1. Program Header Alignment: Flags libraries with 4KB (0x1000) alignment as potentially problematic
2. ELF Analysis: Examines ELF headers for page size assumptions
3. Confidence Scoring: Returns scores from 0-100 based on detection confidence

Raw Readelf Detector

The raw-readelf detector runs configurable rules against readelf output:

npx rn-16kb-check --detectors raw-readelf

Configure rules in config/defaults.json or extend the detector class.

Custom Detectors

Create custom detectors by implementing the Detector interface:

import { Detector, DetectionResult } from 'rn-16kb-support';

class MyDetector implements Detector {
  name = 'my-detector';
  
  async run(filePath: string): Promise<DetectionResult> {
    // Your detection logic here
    return {
      ok: true,
      score: 50,
      reason: 'Custom analysis result'
    };
  }
}

GitHub Actions Integration

Add to your workflow to fail PRs with compatibility issues:

name: Check 16KB Page Size Compatibility
on: [push, pull_request]

jobs:
  check-16kb-support:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Check 16KB compatibility
        run: npx rn-16kb-support --fail-on-issue

How to Fix Issues

When the tool identifies potential issues:

1. Check with library maintainers: Open issues asking about 16KB page size support
2. Update dependencies: Look for newer versions that support 16KB pages
3. Build configuration: Some issues may be resolved by updating build flags
4. Alternative libraries: Consider switching to compatible alternatives

Configuration

Customize detector behavior by modifying config/defaults.json:

{
  "readelfRules": {
    "minSuspiciousAlignment": 4096,
    "badSectionPatterns": [
      ".note.android.ident",
      ".gnu.version"
    ]
  }
}

Development

Building

npm run build

Testing

npm test
npm run test:watch

Linting

npm run lint
npm run lint:fix

Architecture

The tool consists of:

• Scanner: Filesystem traversal to find Android artifacts
• Detectors: Pluggable analysis modules
• CLI: Command-line interface
• API: Programmatic interface for integration

Limitations

• Heuristic-based: Detection is based on common patterns, not definitive analysis
• readelf dependency: Some features require readelf to be available
• False positives: May flag libraries that are actually compatible
• False negatives: May miss some incompatible libraries

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT