npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-native-auto-optimizer

v0.3.1

Published

Find React Native jank at runtime (long JS tasks, heavy lists, oversized images, duplicate fetches) and apply conservative fixes that roll back if they make the app worse

Readme

react-native-auto-optimizer

npm version npm downloads CI License: MIT TypeScript

Find React Native jank at runtime and apply small, reversible fixes — without rewriting your source.

import { AutoOptimizer } from 'react-native-auto-optimizer';

export default function Root() {
  return (
    <AutoOptimizer mode="safe" overlay={__DEV__}>
      <App />
    </AutoOptimizer>
  );
}
npm install react-native-auto-optimizer

This is Phase 6 (0.3.1). Overlay and telemetry are off unless you turn them on. The library does not rewrite files, invent React.memo / getItemLayout, or dedupe POST/PUT/PATCH/DELETE.

What it helps solve

Slow screens usually come from a short list of real problems. Those are hard to catch in code review and easy for users to feel.

| Problem in the app | What users feel | What this library does | | --- | --- | --- | | Long work on the JS thread | Taps and animations hitch | Detects delayed timers as LONG_JS_TASK. Opt-in deferTask() adds a short extra delay after a stall so non-critical work waits. | | A large FlatList with a high initialNumToRender | First paint of a feed is heavy | DetectedFlatList reports the original config. Runtime caps initialNumToRender (and windowSize in smart) on large lists. | | A remote image shown small but decoded huge | Memory spikes, slow image paint | DetectedImage waits for real onLoad size, then may pass display width/height as decode hints. | | The same GET/HEAD fetch in flight more than once | Duplicate loading, extra bandwidth | Instruments fetch, reports duplicates, and shares one in-flight GET/HEAD (smart also caches briefly). | | A named component committing too often | UI work with no user action | useRenderDetector('Name') counts commits and records EXCESSIVE_RENDER. It does not wrap the component in React.memo. | | Native memory pressure | OS warning, possible kill | Listens for memoryWarning when the runtime emits it. Does not invent heap size. |

If a runtime fix is applied, validation watches longTaskCount and (when available) JS heap. Missing metrics are ignored. FPS is left null because there is no honest JS-only FPS API.

It does not try to be a general “make my app fast” compiler. It will not rewrite screens, auto-memo components, invent getItemLayout, change image URLs, or dedupe requests that have a body.

How it works

Wrap the app once with AutoOptimizer. It observes what actually happens, records issues with measured metrics (not guessed FPS), applies a bounded runtime change when a matching rule exists, then measures again. If the change made things worse, it rolls the rule back.

  1. Wrap the root with <AutoOptimizer>. One wrapper owns the process-wide engine.
  2. Detect. JS stalls, duplicate fetch, and memory warnings are observed automatically. Lists, images, and named re-renders need a drop-in (DetectedFlatList, DetectedImage, useRenderDetector) because React Native has no supported hook for every list or image.
  3. Optimize conservatively. safe (default) only applies tight caps. smart may also shrink list windows, cache GET/HEAD, or set resizeMethod="resize". Detection is the same in both modes.
  4. Validate. After validationWindow (default 1s), an applied rule is kept unless metrics regressed. Inconclusive or unchanged results stay applied.
  5. Inspect. overlay is a corner HUD. PerformanceReport is a full page. getReport() is the same data in code. Optional telemetry POSTs that snapshot to your endpoint; nothing is sent by default.

You keep shipping your own screens. The library sits beside them, records evidence, and only changes runtime copies of props or in-flight GET/HEAD calls.

Developer overlay

Pass overlay={__DEV__} for a corner badge (AO {issues}·{applied}). Tap it for live issues and session history.

Default is off, so production binaries do not show a HUD unless you ask.

Requirements

| Requirement | Support | | --- | --- | | React Native | 0.73+ (tested on 0.85 New Architecture) | | React | 18+ (tested on 19) | | Platforms | iOS, Android | | Architecture | Paper and Fabric / concurrent root | | TypeScript | Types shipped in the package | | Expo | Works; JavaScript-only, no config plugin | | Native linking | None in this release |

Peer dependencies:

{
  "react": "*",
  "react-native": "*"
}

Installation

npm install react-native-auto-optimizer
yarn add react-native-auto-optimizer

This release is JavaScript-only. Do not run pod install or change Gradle for this package. Native folders in the repo are reserved for a future Turbo Module and are not autolinked.

No Metro, Babel, or Expo plugin changes are required.

Integration

Do these three steps in any React Native or Expo app.

1. Wrap the application root

Put AutoOptimizer at the top of the tree so detectors and runtime rules cover the whole session. Keep one wrapper.

React Native CLI (App.tsx or the component registered in index.js):

import { AutoOptimizer } from 'react-native-auto-optimizer';
import { App } from './src/App';

export default function Root() {
  return (
    <AutoOptimizer>
      <App />
    </AutoOptimizer>
  );
}

Expo Router (app/_layout.tsx):

import { AutoOptimizer } from 'react-native-auto-optimizer';
import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <AutoOptimizer>
      <Stack />
    </AutoOptimizer>
  );
}

Expo (App.tsx):

import { AutoOptimizer } from 'react-native-auto-optimizer';
import { StatusBar } from 'expo-status-bar';
import { Home } from './Home';

export default function App() {
  return (
    <AutoOptimizer>
      <Home />
      <StatusBar style="auto" />
    </AutoOptimizer>
  );
}

Navigation, Redux/Zustand providers, and Query clients should sit inside AutoOptimizer (or as siblings under the same root). The wrapper does not replace those providers.

2. Choose a development vs production profile

| Setting | Development | Production | | --- | --- | --- | | mode | "safe" or "smart" | "safe" | | debug | true if you want console logs | false | | overlay | true on a debug build | false unless you explicitly want the HUD | | telemetry | devOnlyTelemetry({ endpoint }) + local dashboard | omit, unless you host your own collector | | validation | true (default) | true (default) | | enabled | true | true, or false to disable all work |

import { AutoOptimizer } from 'react-native-auto-optimizer';

export default function Root() {
  return (
    <AutoOptimizer
      mode="safe"
      debug={__DEV__}
      overlay={__DEV__}
      enabled
      validation
    >
      <App />
    </AutoOptimizer>
  );
}

overlay defaults to false so a production binary does not show a badge unless you pass overlay.

3. Opt in where React Native has no global hook

The wrapper starts JS, network, and memory detectors automatically. FlatList, Image, and named-render detection need a drop-in at the screens you care about:

| You want to observe | Use | | --- | --- | | FlatList | DetectedFlatList (same props as FlatList) | | Image | DetectedImage (same props as Image) | | Component re-renders | useRenderDetector('ComponentName') | | Non-critical JS work | deferTask(() => { ... }) | | Duplicate fetch | Nothing extra; fetch is instrumented | | Remote dashboard (dev) | devOnlyTelemetry({ endpoint }) plus yarn dashboard |

Existing FlatList / Image imports are not rewritten. Swap them only where you want detection and runtime caps.

That is the full install. The rest of this document is optional configuration.

Quick start

Minimal wrap (detectors and optimizers on, overlay off, safe mode):

import { AutoOptimizer } from 'react-native-auto-optimizer';
import { App } from './App';

export default function Root() {
  return (
    <AutoOptimizer mode="safe">
      <App />
    </AutoOptimizer>
  );
}

Full configuration:

<AutoOptimizer
  mode="safe"
  debug={__DEV__}
  overlay={__DEV__}
  enabled
  validation
  detection={{
    jsLongTask: true,
    renders: true,
    flatList: true,
    images: true,
    network: true,
    memory: true,
  }}
  optimization={{
    flatList: true,
    network: true,
    images: true,
    jsDeferral: true,
  }}
  thresholds={{
    jsLongTaskThreshold: 50,
    duplicateRequestWindow: 1000,
    excessiveRenderThreshold: 20,
    maxIssues: 100,
    largeFlatListItemThreshold: 500,
    imageOversizeRatio: 2,
    validationWindow: 1000,
  }}
>
  <App />
</AutoOptimizer>

Turn a detector or optimizer off by setting its flag to false. Omitted flags keep the defaults (all true).

Feature integration

FlatList

Replace FlatList with DetectedFlatList on large lists. Detection records the original props. In safe mode a large list’s initialNumToRender is capped at 10; smart also caps windowSize.

import { DetectedFlatList } from 'react-native-auto-optimizer';

function Catalog({ items }) {
  return (
    <DetectedFlatList
      data={items}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => <Row item={item} />}
    />
  );
}

A large data array alone is not an issue. Issues are recorded from list configuration (item count vs initialNumToRender / missing getItemLayout, and so on). getItemLayout is never invented.

Images

Replace Image with DetectedImage. Give the image a numeric width and height in style. Oversize issues are recorded only after onLoad reports real source dimensions.

import { DetectedImage } from 'react-native-auto-optimizer';

function Avatar({ uri }: { uri: string }) {
  return (
    <DetectedImage
      source={{ uri }}
      style={{ width: 80, height: 80 }}
    />
  );
}

safe may pass display size as Image source width/height decode hints. smart may also set resizeMethod="resize" if you did not set it. Image URLs are never rewritten.

Excessive renders

Call useRenderDetector (or trackRender / wrap with RenderProbe) in components you want named. The wrapper cannot name arbitrary components in your tree.

import { useRenderDetector } from 'react-native-auto-optimizer';

function ProductCard() {
  useRenderDetector('ProductCard');
  return <CardBody />;
}

The library does not wrap the component in React.memo. The issue suggestion may mention memoization; applying it stays in your code.

Network

fetch is instrumented when the optimizer is running. Duplicate GET/HEAD calls in duplicateRequestWindow are reported. In-flight GET/HEAD can share one request; smart also caches GET/HEAD briefly (max 20 entries).

await fetch('https://api.example.com/products');

POST, PUT, PATCH, DELETE, and any request with a body are never deduped. XMLHttpRequest / Axios XHR adapters are not instrumented in this release.

JS long tasks and deferred work

Long tasks are detected from setTimeout delay. For non-critical follow-up work, opt in to deferTask. After a LONG_JS_TASK, deferTask() adds a short extra delay (safe 16ms, smart 32ms). Arbitrary JS in your app is not rewritten.

import { deferTask } from 'react-native-auto-optimizer';

function onIdleWork() {
  deferTask(() => {
    // non-critical work
  }).catch(() => {
    // handle failure
  });
}

Memory

MemoryDetector listens for a native memoryWarning event when that event exists. JS heap size is included in validation metrics only if performance.memory exists (often missing on Hermes). Leak hunting is not implemented.

Developer overlay and reports

Overlay (in-app HUD)

Pass overlay on AutoOptimizer. A corner badge shows AO {issues}·{applied}. Tap it for current issues and session optimization history (rule, status, validation, before/after metrics).

<AutoOptimizer overlay={__DEV__} debug={__DEV__}>
  <App />
</AutoOptimizer>

You can also mount PerformanceOverlay yourself:

import { PerformanceOverlay } from 'react-native-auto-optimizer';

<PerformanceOverlay />

This is a local developer overlay. For a browser view of the same snapshots, see Telemetry and remote dashboard.

Telemetry and remote dashboard

Telemetry is off by default. The library never chooses a host. Nothing is sent until telemetry.enabled is true and telemetry.endpoint is set.

This project does not ship a production collector. yarn dashboard is a local, in-memory process for development.

Development (local dashboard)

Use devOnlyTelemetry so a release binary sends nothing, even if the endpoint string is still in the source:

import { AutoOptimizer, devOnlyTelemetry } from 'react-native-auto-optimizer';

<AutoOptimizer
  overlay={__DEV__}
  telemetry={devOnlyTelemetry({
    endpoint: 'http://127.0.0.1:8787/v1/reports',
    appId: 'my-app',
    intervalMs: 10000,
  })}
>
  <App />
</AutoOptimizer>

Android emulator: http://10.0.2.2:8787/v1/reports. Then run yarn dashboard and open http://127.0.0.1:8787.

devOnlyTelemetry(...) returns undefined when __DEV__ is false, which is the same as omitting telemetry.

Production

Default: omit telemetry. Detection, runtime optimizers, validation, and getReport() still work on-device. No performance snapshots leave the phone.

Only enable production POSTs if you run a collector that speaks the same API (POST /v1/reports). Point at HTTPS, not localhost:

<AutoOptimizer
  telemetry={
    __DEV__
      ? devOnlyTelemetry({
          endpoint: 'http://127.0.0.1:8787/v1/reports',
          appId: 'my-app',
        })
      : {
          enabled: true,
          endpoint: 'https://collector.example.com/v1/reports',
          appId: 'my-app',
          apiKey: COLLECTOR_API_KEY,
          intervalMs: 30000,
        }
  }
>
  <App />
</AutoOptimizer>

Store COLLECTOR_API_KEY in your app’s secret/config system. process.env.AO_API_KEY is not injected by this library. If the key is missing, the local dashboard still accepts reports; a locked-down collector should reject them.

POSTs use fetch with header X-Auto-Optimizer-Telemetry: 1, so they are not counted as duplicate app network requests. Failures are logged and never thrown into your UI.

Force a send:

await AutoOptimizer.flushTelemetry();

Run the bundled dashboard

From a clone of this repository (not required for npm install consumers):

yarn dashboard

Open http://127.0.0.1:8787. The server keeps up to 200 snapshots in memory.

| Method | Path | Purpose | | --- | --- | --- | | POST | /v1/reports | Ingest a telemetry envelope | | GET | /v1/reports | List snapshots, newest first | | GET | /v1/reports/:id | One snapshot | | DELETE | /v1/reports | Clear stored snapshots | | GET | /health | Process check |

Optional AO_API_KEY on the server requires Authorization: Bearer … on /v1/*. Set the same value on telemetry.apiKey.

The payload is the current getReport() snapshot plus mode, appId, libraryPhase, and sentAt. There is no default SaaS backend, no AI, and no public website.

Full-page report

import { PerformanceReport } from 'react-native-auto-optimizer';

export function DebugReportScreen() {
  return <PerformanceReport />;
}

Programmatic snapshot

import { AutoOptimizer } from 'react-native-auto-optimizer';

const report = AutoOptimizer.getReport();
// {
//   issues: [...],
//   summary: { totalIssues, critical, high, medium, low },
//   optimizations: [...],
//   optimizationSummary: { total, applied, skipped, failed, rolledBack },
//   history: [...],
//   historySummary: { total, applied, skipped, failed, rolledBack }
// }

AutoOptimizer.clearReport(); // issues + current optimizations
AutoOptimizer.clearHistory(); // session history only

AutoOptimizer.getIssues({ minSeverity: 'high' });
AutoOptimizer.hasIssues({ type: 'LONG_JS_TASK' });
AutoOptimizer.pause();
AutoOptimizer.resume();

const json = AutoOptimizer.exportReport();
const stopListening = AutoOptimizer.subscribe((snapshot) => {
  console.log(snapshot.summary.totalIssues);
});
stopListening();

clearReport() does not erase history. Use clearHistory() for that.

Live UI subscribes to the same snapshot:

import { usePerformanceSnapshot } from 'react-native-auto-optimizer';

function DebugPanel() {
  const snapshot = usePerformanceSnapshot();
  return `${snapshot.summary.totalIssues} issues`;
}

Example issues

{
  type: 'LONG_JS_TASK',
  severity: 'high',
  title: 'Long JavaScript task detected',
  metrics: { duration: 143 }
}

{
  type: 'EXCESSIVE_RENDER',
  component: 'ProductCard',
  severity: 'medium',
  metrics: { renderCount: 25 },
  suggestion: 'Consider React.memo or stabilizing props.'
}

{
  type: 'DUPLICATE_NETWORK_REQUEST',
  severity: 'medium',
  title: 'Duplicate network requests detected',
  metrics: { requestCount: 3, url: '/api/products' }
}

Severity for long JS tasks:

  • 50–99ms: medium
  • 100–200ms: high
  • greater than 200ms: critical

Metrics are recorded only when they can be measured. The library does not fabricate FPS, heap size, image dimensions, or “meaningful prop changes”.

API

AutoOptimizer props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | children | React.ReactNode | required | Application tree to wrap. | | mode | "safe" | "smart" | "safe" | Optimizer policy. Detection is the same in both modes. | | debug | boolean | false | Enables [AutoOptimizer] debug/info logs. Keep false in production. | | enabled | boolean | true | When false, children still render but detectors and optimizers do not start. | | detection | object | all true | Enable or disable individual detectors. | | optimization | object | all true | Enable or disable individual runtime optimizers. | | validation | boolean | true | When true, applied rules are measured after validationWindow and rolled back on regression. | | overlay | boolean | false | When true, render a toggleable in-app HUD over children. | | telemetry | object | off | Optional remote reporting. See Telemetry and remote dashboard. | | thresholds | object | see below | Detector thresholds, issue buffer size, and validation window. |

Thresholds

| Key | Default | Meaning | | --- | --- | --- | | jsLongTaskThreshold | 50 | Milliseconds of timer delay before a LONG_JS_TASK is recorded. | | duplicateRequestWindow | 1000 | Milliseconds used to group duplicate fetch calls (and GET/HEAD cache in smart). | | excessiveRenderThreshold | 20 | Named-component commits before EXCESSIVE_RENDER. | | maxIssues | 100 | Issue buffer size. | | largeFlatListItemThreshold | 500 | Item count treated as a large list for FlatList rules. | | imageOversizeRatio | 2 | Source pixels vs display size before IMAGE_PERFORMANCE. | | validationWindow | 1000 | Milliseconds to wait after an applied rule before measuring and possibly rolling back. |

Invalid or non-positive threshold values fall back to these defaults.

Statics

| Method | Description | | --- | --- | | AutoOptimizer.getReport() | Current issues, optimizations, and session history. | | AutoOptimizer.getIssues(query?) | Issues, optionally filtered by type, severity, category, component, or minSeverity. | | AutoOptimizer.hasIssues(query?) | Whether any issues match the optional query. | | AutoOptimizer.getHistory(query?) | Session optimization history, optionally by ruleId / status. | | AutoOptimizer.getMetrics() | Current measured metrics (longTaskCount, heap if exposed; FPS stays null). | | AutoOptimizer.getStatus() / isRunning() | Engine lifecycle: idle | ready | running. | | AutoOptimizer.getConfig() | Resolved wrapper config. | | AutoOptimizer.subscribe(listener) | Call on each report change. Returns an unsubscribe function. | | AutoOptimizer.reportIssue(input) | Record a custom issue (and apply matching runtime rules if running). | | AutoOptimizer.exportReport() | JSON.stringify of getReport(). | | AutoOptimizer.pause() / resume() | Stop or restart detectors without unmounting the wrapper. | | AutoOptimizer.clearReport() | Clears issues and current optimizations. Does not clear history. | | AutoOptimizer.clearHistory() | Clears session history only. | | AutoOptimizer.flushTelemetry() | POSTs the current snapshot when telemetry is enabled. |

Main exports

import {
  AutoOptimizer,
  DetectedFlatList,
  DetectedImage,
  PerformanceOverlay,
  PerformanceReport,
  RenderProbe,
  deferTask,
  devOnlyTelemetry,
  trackRender,
  usePerformanceSnapshot,
  useRenderDetector,
} from 'react-native-auto-optimizer';

Debug logs

When debug={true}:

[AutoOptimizer] Started
[AutoOptimizer] Long JavaScript task detected
Duration: 143ms

Repeated identical warnings are throttled. debug and info logs are silent when debug is false. warn / error still emit.

Modes

safe vs smart only changes optimizer policy, not detection.

| Rule | safe | smart | | --- | --- | --- | | FlatListOptimizer (flatlist-runtime) | Cap initialNumToRender at 10 on large DetectedFlatLists | Also cap windowSize at 10 | | NetworkDedupeOptimizer (network-dedupe) | In-flight GET/HEAD share one fetch | Also cache GET/HEAD for duplicateRequestWindow ms (max 20 entries) | | ImageDecodeOptimizer (image-decode) | Known display size as Image source width/height hints | Also resizeMethod="resize" if unset | | JsDeferralOptimizer (js-deferral) | After LONG_JS_TASK, deferTask() adds a short extra delay | Same, with a slightly longer extra delay |

Matching synchronous rules are applied automatically when an issue is reported. After validationWindow ms, an after snapshot is captured. If measured signals got worse, the rule is rolled back.

Metrics are compared only when they can be measured:

  • longTaskCount: LONG_JS_TASK issues recorded in the validation window
  • memoryUsageBytes: performance.memory.usedJSHeapSize when the runtime exposes it
  • jsFps / uiFps / droppedFrames: remain null (no JS-only FPS API)

Missing metrics are ignored. A rule is not rolled back just because FPS could not be measured.

Detectors

| Detector | Issue type | How it works | Integration | | --- | --- | --- | --- | | JSLongTaskDetector | LONG_JS_TASK | Measures setTimeout delay. A delayed callback means the JS thread was busy. | Automatic after wrap | | RenderDetector | EXCESSIVE_RENDER | Counts named renders via useRenderDetector, trackRender, or RenderProbe. | Opt-in hook / probe | | FlatListDetector | FLATLIST_PERFORMANCE | Observes DetectedFlatList configuration. | DetectedFlatList | | ImageDetector | IMAGE_PERFORMANCE | Observes DetectedImage after onLoad reports real source dimensions. | DetectedImage | | DuplicateNetworkDetector | DUPLICATE_NETWORK_REQUEST | Observes fetch duplicates in a sliding window. Observes original requests. | Automatic after wrap | | MemoryDetector | MEMORY_WARNING | Listens for native memoryWarning when that event exists. Does not invent heap size. | Automatic after wrap |

Detection still observes original props. Optimizers mutate a runtime copy passed to the native component.

Runtime optimizers

See Modes for safe vs smart. Each optimizer can be disabled with optimization={{ flatList: false }} (or network, images, jsDeferral).

React.memo and getItemLayout are never invented. POST/PUT/PATCH/DELETE are never deduped.

TypeScript

The package ships .d.ts files. No extra @types package is required.

import type {
  AutoOptimizerProps,
  PerformanceIssue,
  PerformanceReportSnapshot,
} from 'react-native-auto-optimizer';

DetectedFlatList accepts FlatListProps<ItemT>. DetectedImage accepts ImageProps.

Architecture

AutoOptimizer
        ↓
OptimizerEngine
        ↓
PerformanceMonitor → DetectorEngine → detectors → PerformanceIssue
        ↓
runtime rules (sync auto-apply) → OptimizationResult
        ↓
measure after validationWindow → rollback on regression
        ↓
session history + overlay / PerformanceReport
        ↓
optional telemetry POST → local dashboard

AutoOptimizer owns the process-wide OptimizerEngine. Detectors observe; matching runtime rules may change copies of props or share in-flight GET/HEAD fetch calls. Applied rules are validated against real metrics and rolled back if they regress. The overlay reads the same report and session history. Telemetry, if enabled, POSTs that same snapshot to your endpoint.

Known limitations

  • Render detection requires useRenderDetector, trackRender, or RenderProbe. The wrapper cannot name arbitrary components in your tree.
  • FlatList and Image detection/optimization require DetectedFlatList / DetectedImage (or the observeFlatList / observeImage APIs). Existing FlatList / Image imports are not rewritten.
  • Image oversize issues are recorded only after onLoad provides source width/height and a numeric display size is present in style.
  • Duplicate network detection currently instruments fetch, not XMLHttpRequest.
  • JS heap size is omitted on Hermes and other runtimes that do not expose performance.memory.
  • Memory leak detection is not implemented.
  • safe / smart does not change detection; it only changes optimizer policy.

What is not supported yet

Not in this release:

  • Automatic React.memo wrapping
  • Inventing getItemLayout
  • Deduplicating POST/PUT/PATCH/DELETE (or any request with a body)
  • Rewriting image URLs
  • Automatically wrapping arbitrary JS work (deferTask is opt-in)
  • Fabricating FPS or heap size when the runtime does not expose them
  • A hosted SaaS, website, or AI analysis

Telemetry exists but is optional and off by default. The bundled dashboard is a local process, not a public website.

Wrapping your app remains conservative: detectors observe original behavior, and only the runtime rules above apply bounded fixes.

Troubleshooting

| Symptom | What to check | | --- | --- | | Package not found | Install react-native-auto-optimizer in the app workspace, not only a parent repo. Restart Metro with --reset-cache after the first install. | | Overlay missing | Pass overlay (or overlay={__DEV__}). Default is off. | | No FlatList / image issues | Swap those screens to DetectedFlatList / DetectedImage. Give images numeric style width and height. | | No render issues | Call useRenderDetector('Name') in the component. | | No network issues | Use global fetch. Axios-on-XHR is not observed. POSTs are never deduped. | | Native build / autolink errors | This package disables iOS/Android autolinking. You should not add pods or Gradle entries for it. | | Extra production overlay | Keep overlay false in release. Gate with __DEV__. | | Telemetry 403 / nothing in the dashboard | Dev: devOnlyTelemetry + yarn dashboard. Android emulator needs 10.0.2.2. Production: omit telemetry unless you host a collector. | | Snapshots leaving a release app | Omit telemetry, or use devOnlyTelemetry so __DEV__ === false sends nothing. | | Want a no-op wrap | <AutoOptimizer enabled={false}> still renders children. |

Development

This repository is a Yarn 4 workspace. Use Yarn, not npm, for local development of the library.

yarn
yarn test
yarn typecheck
yarn prepare

Optional local dashboard (open http://127.0.0.1:8787):

yarn dashboard

Run the example app (includes screens that trigger JS stalls, extra renders, a large list, duplicate fetches, and images). The example POSTs snapshots to the dashboard when that process is running:

yarn example start
yarn example ios
yarn example android

On iOS, install pods first:

cd example
bundle install
bundle exec pod install --project-directory=ios

The example app is New Architecture by default (newArchEnabled=true).

See CONTRIBUTING.md for the full development workflow.

Roadmap

| Phase | Focus | | --- | --- | | 1 | Foundation and public API | | 2 | Detectors: JS long-task, render, FlatList, image, network, memory | | 3 | Optimizers: FlatList, network request deduplication, safe JS task deferral, image optimization | | 4 | Before/after measurement, validation, rollback | | 5 | Developer performance overlay, reports, optimization history | | 6 | Optional telemetry, local backend, remote dashboard (current, 0.3.1) |

License

MIT