DevtoolsProvider
The provider's props, and every configuration option underneath them.
import { DevtoolsProvider } from '@axonpack/expo-devtools';
<DevtoolsProvider config={config}>
<YourApp />
</DevtoolsProvider>;Wrap your app in it once, at the root. It starts the devtools as it renders, which is before any
child's mount, and hosts the panel. There is no init to call.
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
config | DevtoolsConfig | {} | Everything below. Read once, on the first render. |
showFloatingButton | boolean | true | Draw the launcher button. Off leaves the panel reachable through useDevtoolsPanel. |
iconComponent | ComponentType<{ size: number }> | none | Renders in place of the built-in glyph. Given the resolved size. |
size | number | 44 | Diameter of the button, in dp. |
color | string | accent | Button fill. |
iconColor | string | '#ffffff' | The built-in glyph only; an iconComponent colours itself. |
statusBar | 'auto' | 'app' | 'light' | 'dark' | 'auto' | What the status bar's clock and icons do while the panel is open. |
children | ReactNode | none | Your app. |
The provider is generic over your theme names, so config.defaultTheme accepts a built-in id or a key
of config.themes and nothing else.
The button is draggable, stays inside the screen, and keeps a 44dp touch area through hitSlop even at
a smaller size. Rendering it is also what marks first render for the startup breakdown.
statusBar
The panel never paints a status bar background of its own: the header extends behind it, so that area is already the toolbar's colour. What this prop decides is the content.
| Value | What happens |
|---|---|
'auto' | Follows the theme, each of which carries its own statusBarStyle. A dark theme gets light icons, a light one dark. |
'app' | Untouched, for an app that manages the status bar itself. |
'light'/'dark' | That content style whatever the theme is on. 'light' means light icons, for a dark background. |
Whatever the app had is restored when the panel closes. Without this, a light app's dark icons stay dark and become unreadable over a dark panel.
iOS needs one Info.plist key
React Native's StatusBar cannot change the style unless UIViewControllerBasedStatusBarAppearance
is false in Info.plist. An Expo app's own template already sets it, so there is usually nothing
to do. If yours does not, statusBar has no effect on iOS and 'app' is the honest setting.
Top level
| Option | Type | Default | What it does |
|---|---|---|---|
enabled | boolean | true | Whether the devtools run at all. The only gate; see Leaving it in production. |
defaultTheme | ThemeId | 'light' | Which theme the panel opens with: a built-in or one of yours. |
themes | Record<string, ThemeConfig> | undefined | Your own themes: a base to inherit and the tokens to override. |
With enabled: false the provider renders its children and the crash sheet and nothing else: no
patches, no button, no panel. The config is read on the first render and never again, because the
patches are global and go in one time, so enabled cannot be flipped mid-session.
Network
The switches name the kind of traffic, not the mechanism that carried it. A request is a request
whether it went out through fetch, through XMLHttpRequest, from a JSI client or from inside a page.
| Option | Type | Default | What it does |
|---|---|---|---|
network.http | boolean | true | Capture plain requests, by whatever transport they left on. Off also means no phase timing. |
network.websocket | boolean | true | Capture WebSocket connections and their messages, the app's own and a page's. |
network.sse | boolean | true | Capture server-sent event streams and their events, whichever client opened them. |
network.disabledByDefault | boolean | false | Open the Network tab paused. |
network.redactHeaders | readonly string[] | [] | Header names whose values are stored as [redacted], matched without regard to case. Listing cookie also redacts a page's document.cookie. |
network.redact | (entry: NetworkEntry) => NetworkEntry | null | undefined | Runs after redactHeaders, each time an entry changes, before it is stored. An entry is an HTTP row (NetworkLogEntry) or a WebSocket row, told apart by kind. Return the entry, edited or not, or null to drop the row. If it throws, the row is dropped. |
With sse off, the app's own stream is still recognised as one. Its endless body has to be, or it
would be read as a response. So the row remains and only the events are dropped. A page's stream has no
request underneath it that anything here can see, so that one disappears entirely.
Redaction happens before a request is stored, so nothing downstream sees the real value: not the list,
the detail panel, copy, export, the DevTools tab or crash breadcrumbs. Replaying a request from the panel
sends the placeholder too. redactHeaders covers HTTP rows only, while redact sees WebSocket rows
too. Socket frames and stream events pass through neither. See
Redaction.
network: {
redactHeaders: ['authorization', 'cookie', 'set-cookie'],
redact: (entry) => ({ ...entry, url: entry.url.replace(/token=[^&]+/, 'token=[redacted]') }),
}Console
| Option | Type | Default | What it does |
|---|---|---|---|
console.capture | boolean | true | Mirror console.* into the Console tab, including from WebViews wired with useDevtoolsWebView. |
console.repl | boolean | true | Show the > prompt. |
console.context | Record<string, unknown> | undefined | Extra names an expression can use, for example { store, queryClient }. A support can add names of its own, such as preview; yours win a clash. |
console.redactKeys | readonly (string | RegExp)[] | [] | Names and keys whose values the CLI's context topic shows as [redacted]: an exposed name, any segment of a dot path such as session.token, and a key at any depth in an object, array or Map it prints. A string matches a whole key without regard to case; a RegExp is tested as written. |
console.redact | (name: string, value: unknown) => unknown | undefined | Runs after redactKeys on each context value the CLI is about to show, with the name or dot path and the value as the CLI prints it. The CLI shows what it returns. It also gets the message when a call throws. If it throws, the value shows as [redacted]. |
console.disabledByDefault | boolean | false | Open the Console tab paused. The prompt still works. |
console.redactKeys and console.redact cover what leaves through the CLI: the context list,
devtools get context and what devtools context call returns, and so the CLI tab's log of them.
They run before a value is printed, cut or logged. The > prompt isn't redacted, since it runs
whatever is typed on the device, and neither are the arguments a caller passes to call.
console: {
context: { session, store },
redactKeys: ['token', /secret/i],
redact: (name, value) => (name === 'session.user' ? { ...(value as object), email: '[redacted]' } : value),
}console.repl is not gated on __DEV__
It defaults to true in every build. Wherever the devtools are on the prompt is there, including in
a release build, where it runs whatever is typed into it. Ship with enabled: false, or set
console: { repl: false }.
Performance
| Option | Type | Default | What it does |
|---|---|---|---|
performance.sampleIntervalMs | number | 1000 | How often memory is sampled. Each read crosses into the engine, so keep it coarse. |
performance.longTaskThresholdMs | number | 150 | Only keep tasks that blocked the JS thread at least this long. |
performance.interactionThresholdMs | number | 100 | Only keep interactions at least this long, event to next paint. |
performance.historySize | number | 120 | How many memory samples, long tasks, user timings and interactions are kept. |
performance.disabledByDefault | boolean | true | Open the Performance tab paused. Defaults to on, since measuring costs something. |
Storage
| Option | Type | Default | What it does |
|---|---|---|---|
storage.adapters | StorageAdapterDefinition[] | undefined | The stores the Storage tab can see. Nothing is discovered automatically. |
storage.maxKeys | number | undefined | Deprecated and ignored. Every key is listed, and a value is read when its row is on screen. |
storage.readOnly | boolean | false | Blanket read-only default; an individual adapter can still set its own. |
storage.redactKeys | readonly (string | RegExp)[] | [] | Keys whose values are shown as [redacted], in every store. A string matches a whole key without regard to case; a RegExp is tested as written. |
storage.redact | (entry: StorageEntry) => StorageEntry | null | undefined | Runs after redactKeys, each time a value is read, before the tab keeps it. Return the entry with its text changed, the entry as it is, or null to hide the key. If it throws, the key is hidden. Only text is taken from what it returns. |
See Storage adapters for how to build one.
Redaction happens as a value is read, live changes included, so nothing downstream sees the real
value: not the list, the detail sheet, copy, export or the DevTools tab. A redacted value can't be
edited or deleted, and an import skips it, so the placeholder is never written back. A key redact
hid stays on the list until its value is read; a blacklist keeps it off the list entirely. See
Redaction.
storage: {
adapters,
redactKeys: ['authToken', /^session\./],
// Every SecureStore value. Its id is its name, slugged.
redact: (entry) =>
entry.adapterId === 'securestore' && entry.text !== null
? { ...entry, text: '[redacted]' }
: entry,
}Query
| Option | Type | Default | What it does |
|---|---|---|---|
query.client | QueryClientLike | undefined | Your app's TanStack Query v5 QueryClient, the same one passed to QueryClientProvider. Unset leaves the Query tab out of the panel. |
TanStack Query is not a dependency of this package, so the Query tab sees only the client handed to it here. From the tab you can refetch, invalidate, reset or remove a query, or hold it in a loading or error state.
query: { client: queryClient },Navigation
| Option | Type | Default | What it does |
|---|---|---|---|
navigation.disabledByDefault | boolean | false | Open the Navigation tab paused. The route on screen is still shown. |
navigation.redact | (move: NavigationMove) => NavigationMove | null | undefined | Runs on every move before it is stored, including the route shown as current. Return the move, edited or not, or null to drop it. If it throws, the move is dropped. |
The tab is there only when a router is installed. Expo Router is found on its own. So is a React
Navigation container the provider sits inside. A container mounted inside the provider is handed over
with useDevtoolsNavigation.
What redact returns is all anything downstream sees: the history, the tree, copy, export and crash
reports.
navigation: {
redact: (move) =>
move.to?.params && 'token' in move.to.params
? { ...move, to: { ...move.to, params: { ...move.to.params, token: '[redacted]' } } }
: move,
}See Navigation and the Navigation tab.
Redux
The Redux tab is there once a store was created with
devtoolsReduxEnhancer().
| Option | Type | Default | What it does |
|---|---|---|---|
redux.disabledByDefault | boolean | false | Open the Redux tab paused. The current state is still shown. |
redux.allow | ActionTypeMatcher[] | undefined | Record only these action types. A string matches one type exactly, a RegExp is tested against it. Empty or left out, every type is recorded. |
redux.deny | ActionTypeMatcher[] | undefined | Never record these types, for the action an app fires dozens of times a second. Wins over allow. More can be added from the panel while the app runs. |
redux: {
allow: [/^cart\//, 'auth/signedIn'],
deny: ['timer/tick', /^analytics\//],
},Supports
A support connects the devtools to another package. Each has its own entry point,
@axonpack/expo-devtools/support/<name>/v<major>, where <major> is the major version of the
package it supports, and the main entry has none of them. The guide is
Supports.
| Option | Type | Default | What it does |
|---|---|---|---|
supports | DevtoolsSupport[] | undefined | The supports to turn on, each from its module's configure(). Read once like the rest of the config. A support can put a provider around the app, with enabled: false too, add a tab before Crashes in the panel and in React Native DevTools, add a topic to the devtools command line tool, and add names to the > prompt. With the devtools on, a support whose package isn't installed, or is on another major, has the reason logged with console.error at start and shown in its tab. Nothing throws. With two supports of one id, such as two versions of one support, the first is used and the start logs the other with console.error |
Every support module exports the same shape:
| Export | Kind | What it is |
|---|---|---|
configure(config) | function | Takes the package's own config and returns a DevtoolsSupport for supports. Never throws |
useSupport() | hook | The support's data, from the store its provider fills. The same name in every support |
| default export | object | The same functions, so a default import and a namespace import read alike (X.configure) |
| config types | types | The package's config types, re-exported, so the setup needs no import from the package. Named exports only; any in an app without the package |
| data type | type | What useSupport() returns |
DevtoolsSupport | type | What configure returns. Also exported from the main entry |
What a support adds besides its tab, its panel and useSupport():
| Part | What it is |
|---|---|
| A command line topic | A topic of the devtools tool named after the support, listed by devtools topics only while the support is in supports. An off topic, with the error as its reason, when the package isn't installed or is on another major. See Topics from supports |
Names in the > prompt | Optional. Reachable next to console.context, which wins a clash |
import PreviewV0Support from '@axonpack/expo-devtools/support/preview/v0';
// or
import * as PreviewV0Support from '@axonpack/expo-devtools/support/preview/v0';
// or
import { configure, type PreviewConfig } from '@axonpack/expo-devtools/support/preview/v0';
supports: [PreviewV0Support.configure(previewConfig)],Preview support
@axonpack/expo-devtools/support/preview/v0, for @axonpack/preview 0.x, 0.2.0
or later.
It mounts preview's provider and adds the Preview tab, the preview topic of the devtools tool
(see preview and its
actions), and preview in the > prompt. See
Preview support.
| Export | Kind | What it is |
|---|---|---|
configure(config) | function | Takes a PreviewConfig and returns a DevtoolsSupport |
useSupport() | hook | { status, previews, servers }: what usePreviewStatus() returns (null until preview's provider has rendered), usePreview().items, and the dev servers the last look found |
| default export | object | { configure, useSupport } |
PreviewConfig | type | Preview's config, the object its PreviewProvider takes. Its fields are on preview's Reference |
PreviewS3Config | type | PreviewConfig['s3Config']: the bucket and how to read it |
DevPreviewServersOptions | type | devPreviewServers as an object: enabled, allowCustomHosts and hosts |
PreviewSupportData | type | What useSupport() returns |
DevtoolsSupport | type | What configure returns |
In the > prompt, preview has status, previews and servers, the same as useSupport(), and
switch(id) and default(), the topic's actions with no --yes. Each returns the line the
devtools tool would print.
With @axonpack/preview missing, the start logs this, the Preview tab shows it, and the preview
topic is off with it as the reason:
The devtools config sets up preview, but @axonpack/preview isn't installed. Install it with `npx expo install @axonpack/preview expo-file-system`, add `@axonpack/preview` to the plugins in app.json, and rebuild the app.With another major of @axonpack/preview installed, 1.0.0 here, it logs and shows this instead:
The devtools config uses @axonpack/expo-devtools/support/preview/v0, which is for @axonpack/preview 0.x, but @axonpack/preview 1.0.0 is installed. Import the support from `@axonpack/expo-devtools/support/preview/v1` instead, and update @axonpack/expo-devtools if it doesn't have that entry yet.Crash
Crash capture is the only part of this package that runs with the devtools off, apart from the supports' providers.
| Option | Type | Default | What it does |
|---|---|---|---|
crash.enabled | boolean | true | Capture at all. |
crash.enableWhileDevtoolsDisabled | boolean | false | Install the handlers even with enabled: false, so a release build still reports crashes. |
crash.handlers.jsErrors | boolean | true | The ErrorUtils global handler, for fatal and non-fatal JS errors. |
crash.handlers.unhandledRejections | boolean | true | Unhandled promise rejections, via the Hermes rejection tracker. |
crash.handlers.nativeExceptions | boolean | true | Uncaught Java/Kotlin and Objective-C exceptions, via the native module. |
crash.popupDetail | 'auto' | 'full' | 'compact' | 'auto' | Which sheet a crash opens. 'auto' is the full sheet when the devtools are enabled, compact when not. |
crash.disableDefaultLogBox | boolean | false | Uninstall React Native's LogBox, so a JS error is reported here and nowhere else. |
crash.breadcrumbs | boolean | true | Attach the recent console, network and navigation entries to each record. |
crash.maxBreadcrumbs | number | none | Not used yet: a record carries every breadcrumb the Console, Network and Navigation tabs hold, whatever this says. |
crash.maxRecords | number | 25 | Reports kept in memory. |
crash.persistNonFatal | boolean | false | Also write non-fatal records to disk. |
crash.redact | (record: CrashRecord) => CrashRecord | null | undefined | Runs before the record reaches the store, the disk or onCrash. Return null to drop it. |
crash.onCrash | (record: CrashRecord) => void | undefined | Your own handler, after redact. |
With the devtools off, an app relying on enableWhileDevtoolsDisabled alone installs nativeExceptions
only, whatever the other two say: the JS tiers report errors the app survived, which is a developer's
concern, and the sheet there is in front of a user. A fatal JS error still arrives, because React Native turns it
into a native exception on the way to killing the process.
disableDefaultLogBox uninstalls LogBox rather than muting it, which takes the yellow warning toasts
with it. LogBox is one component and the two cannot be separated. Warnings are still captured by the
Console tab. It only does anything in development; LogBox is already an empty stub in a release build.
CLI
| Option | Type | Default | What it does |
|---|---|---|---|
cli.disabledByDefault | boolean | false | Open the CLI tab paused, so no query is kept until you press record. Agents can still query the app. |
aiUsage.disabledByDefault | boolean | false | Deprecated. The old name of cli.disabledByDefault, which wins when both are set. |
The command line tool agents use needs nothing in the config. It answers whenever the devtools are enabled in a development bundle, and every redaction option above applies to what it reads. See Use with AI agents and the CLI tab.
Related components
| Component | What it is for |
|---|---|
<CrashReportOverlay /> | The crash sheet on its own, for a build that ships crash reporting but not the panel. The provider mounts one itself, with the devtools on or off; mounting both is harmless. |
<DevtoolsErrorBoundary /> | Catches render errors, the only tier that produces a component stack. Props: children, fallback(error, reset), onError(error, info). |
React Native DevTools tab
Every control in the Axonpack tab on your computer: the bar, and the Network, Console, Performance, Storage, Preview, Crashes, CLI and Debug panels.
Hooks and the devtools object
useDevtoolsPanel, useDevtoolsWebView, useDevtoolsNavigation, and the module-level devtools object.