Axonpack
Reference

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

PropTypeDefaultWhat it does
configDevtoolsConfig{}Everything below. Read once, on the first render.
showFloatingButtonbooleantrueDraw the launcher button. Off leaves the panel reachable through useDevtoolsPanel.
iconComponentComponentType<{ size: number }>noneRenders in place of the built-in glyph. Given the resolved size.
sizenumber44Diameter of the button, in dp.
colorstringaccentButton fill.
iconColorstring'#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.
childrenReactNodenoneYour 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.

ValueWhat 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

OptionTypeDefaultWhat it does
enabledbooleantrueWhether the devtools run at all. The only gate; see Leaving it in production.
defaultThemeThemeId'light'Which theme the panel opens with: a built-in or one of yours.
themesRecord<string, ThemeConfig>undefinedYour 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.

OptionTypeDefaultWhat it does
network.httpbooleantrueCapture plain requests, by whatever transport they left on. Off also means no phase timing.
network.websocketbooleantrueCapture WebSocket connections and their messages, the app's own and a page's.
network.ssebooleantrueCapture server-sent event streams and their events, whichever client opened them.
network.disabledByDefaultbooleanfalseOpen the Network tab paused.
network.redactHeadersreadonly 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 | nullundefinedRuns 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

OptionTypeDefaultWhat it does
console.capturebooleantrueMirror console.* into the Console tab, including from WebViews wired with useDevtoolsWebView.
console.replbooleantrueShow the > prompt.
console.contextRecord<string, unknown>undefinedExtra 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.redactKeysreadonly (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) => unknownundefinedRuns 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.disabledByDefaultbooleanfalseOpen 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

OptionTypeDefaultWhat it does
performance.sampleIntervalMsnumber1000How often memory is sampled. Each read crosses into the engine, so keep it coarse.
performance.longTaskThresholdMsnumber150Only keep tasks that blocked the JS thread at least this long.
performance.interactionThresholdMsnumber100Only keep interactions at least this long, event to next paint.
performance.historySizenumber120How many memory samples, long tasks, user timings and interactions are kept.
performance.disabledByDefaultbooleantrueOpen the Performance tab paused. Defaults to on, since measuring costs something.

Storage

OptionTypeDefaultWhat it does
storage.adaptersStorageAdapterDefinition[]undefinedThe stores the Storage tab can see. Nothing is discovered automatically.
storage.maxKeysnumberundefinedDeprecated and ignored. Every key is listed, and a value is read when its row is on screen.
storage.readOnlybooleanfalseBlanket read-only default; an individual adapter can still set its own.
storage.redactKeysreadonly (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 | nullundefinedRuns 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

OptionTypeDefaultWhat it does
query.clientQueryClientLikeundefinedYour 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 },
OptionTypeDefaultWhat it does
navigation.disabledByDefaultbooleanfalseOpen the Navigation tab paused. The route on screen is still shown.
navigation.redact(move: NavigationMove) => NavigationMove | nullundefinedRuns 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().

OptionTypeDefaultWhat it does
redux.disabledByDefaultbooleanfalseOpen the Redux tab paused. The current state is still shown.
redux.allowActionTypeMatcher[]undefinedRecord 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.denyActionTypeMatcher[]undefinedNever 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.

OptionTypeDefaultWhat it does
supportsDevtoolsSupport[]undefinedThe 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:

ExportKindWhat it is
configure(config)functionTakes the package's own config and returns a DevtoolsSupport for supports. Never throws
useSupport()hookThe support's data, from the store its provider fills. The same name in every support
default exportobjectThe same functions, so a default import and a namespace import read alike (X.configure)
config typestypesThe 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 typetypeWhat useSupport() returns
DevtoolsSupporttypeWhat configure returns. Also exported from the main entry

What a support adds besides its tab, its panel and useSupport():

PartWhat it is
A command line topicA 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 > promptOptional. 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.

ExportKindWhat it is
configure(config)functionTakes 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 exportobject{ configure, useSupport }
PreviewConfigtypePreview's config, the object its PreviewProvider takes. Its fields are on preview's Reference
PreviewS3ConfigtypePreviewConfig['s3Config']: the bucket and how to read it
DevPreviewServersOptionstypedevPreviewServers as an object: enabled, allowCustomHosts and hosts
PreviewSupportDatatypeWhat useSupport() returns
DevtoolsSupporttypeWhat 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.

OptionTypeDefaultWhat it does
crash.enabledbooleantrueCapture at all.
crash.enableWhileDevtoolsDisabledbooleanfalseInstall the handlers even with enabled: false, so a release build still reports crashes.
crash.handlers.jsErrorsbooleantrueThe ErrorUtils global handler, for fatal and non-fatal JS errors.
crash.handlers.unhandledRejectionsbooleantrueUnhandled promise rejections, via the Hermes rejection tracker.
crash.handlers.nativeExceptionsbooleantrueUncaught 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.disableDefaultLogBoxbooleanfalseUninstall React Native's LogBox, so a JS error is reported here and nowhere else.
crash.breadcrumbsbooleantrueAttach the recent console, network and navigation entries to each record.
crash.maxBreadcrumbsnumbernoneNot used yet: a record carries every breadcrumb the Console, Network and Navigation tabs hold, whatever this says.
crash.maxRecordsnumber25Reports kept in memory.
crash.persistNonFatalbooleanfalseAlso write non-fatal records to disk.
crash.redact(record: CrashRecord) => CrashRecord | nullundefinedRuns before the record reaches the store, the disk or onCrash. Return null to drop it.
crash.onCrash(record: CrashRecord) => voidundefinedYour 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

OptionTypeDefaultWhat it does
cli.disabledByDefaultbooleanfalseOpen the CLI tab paused, so no query is kept until you press record. Agents can still query the app.
aiUsage.disabledByDefaultbooleanfalseDeprecated. 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.

ComponentWhat 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).

On this page