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
Maintainers
Readme
react-native-auto-optimizer
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-optimizerThis 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
- How it works
- Developer overlay
- Requirements
- Installation
- Integration
- Quick start
- Feature integration
- Developer overlay and reports
- Telemetry and remote dashboard
- API
- Modes
- Detectors
- Runtime optimizers
- TypeScript
- Known limitations
- Troubleshooting
- Development
- Roadmap
- License
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.
- Wrap the root with
<AutoOptimizer>. One wrapper owns the process-wide engine. - 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. - Optimize conservatively.
safe(default) only applies tight caps.smartmay also shrink list windows, cache GET/HEAD, or setresizeMethod="resize". Detection is the same in both modes. - Validate. After
validationWindow(default 1s), an applied rule is kept unless metrics regressed. Inconclusive or unchanged results stay applied. - Inspect.
overlayis a corner HUD.PerformanceReportis a full page.getReport()is the same data in code. OptionaltelemetryPOSTs 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-optimizeryarn add react-native-auto-optimizerThis 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 dashboardOpen 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: 143msRepeated 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_TASKissues recorded in the validation windowmemoryUsageBytes:performance.memory.usedJSHeapSizewhen the runtime exposes itjsFps/uiFps/droppedFrames: remainnull(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 dashboardAutoOptimizer 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, orRenderProbe. The wrapper cannot name arbitrary components in your tree. - FlatList and Image detection/optimization require
DetectedFlatList/DetectedImage(or theobserveFlatList/observeImageAPIs). ExistingFlatList/Imageimports are not rewritten. - Image oversize issues are recorded only after
onLoadprovides source width/height and a numeric display size is present instyle. - Duplicate network detection currently instruments
fetch, notXMLHttpRequest. - JS heap size is omitted on Hermes and other runtimes that do not expose
performance.memory. - Memory leak detection is not implemented.
safe/smartdoes not change detection; it only changes optimizer policy.
What is not supported yet
Not in this release:
- Automatic
React.memowrapping - Inventing
getItemLayout - Deduplicating POST/PUT/PATCH/DELETE (or any request with a body)
- Rewriting image URLs
- Automatically wrapping arbitrary JS work (
deferTaskis 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 prepareOptional local dashboard (open http://127.0.0.1:8787):
yarn dashboardRun 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 androidOn iOS, install pods first:
cd example
bundle install
bundle exec pod install --project-directory=iosThe 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
