Plugin Options

All options are optional. reactNative() with no arguments works for any real RN app.

reactNative({
  engine: 'auto',        // 'native' | 'mock' | 'auto' (default: 'auto' → native when available)
  platform: 'ios',       // 'ios' | 'android' (default: 'ios')
  diagnostics: false,    // Log plugin activity (default: false)
  presets: [],           // Third-party library presets
  mocks: {},             // Custom mock overrides
  assetExts: [],         // Additional asset extensions (e.g. ['.lottie', '.m4b'])
  transform: [],         // Extra node_modules packages to transform (Flow/TS/JSX), native engine
  hotRuntime: false,     // Experimental hot runtime for large native suites
})

engine

Which engine to use. See Choosing an Engine for the full breakdown.

• 'auto' (default) — native when @react-native/babel-preset + @babel/core are present, else mock with a one-line notice.
• 'native' — force real React Native; mock only the native boundary.
• 'mock' — force the fast pure-JS mock.

platform

'ios' (default) or 'android'. Controls which platform-specific file extension wins during resolution (.ios.ts vs .android.ts) and the value of Platform.OS. Switch per-test at runtime with setPlatform.

diagnostics

Set to true to log plugin activity — useful when debugging resolution or which engine resolved. Default false.

presets

An array of third-party presets. Presets are auto-detected from your installed dependencies, so listing them is usually optional:

import { reactNative, presets } from 'vitest-native'

reactNative({
  presets: [presets.reanimated(), presets.navigation()],
})

mocks

Custom mock overrides, keyed by export name. Useful for the handful of unstable/private RN exports that aren't mocked:

reactNative({
  mocks: {
    unstable_NativeText: MyCustomMock,
  },
})

assetExts

Additional asset extensions to stub, beyond the built-in defaults:

reactNative({
  assetExts: ['.lottie', '.m4b'],
})

transform

(Native engine.) Extra node_modules packages whose source should be transformed (Flow/TS/JSX) — the vitest-native equivalent of Jest's transformIgnorePatterns. Use it for pure-JS third-party libraries that ship untranspiled source:

reactNative({
  transform: ['some-untranspiled-lib'],
})

hotRuntime

(Native engine, experimental.) Keeps React Native warm across files for large suites, resetting app/test modules and common process-wide pollution between files. Uses Vitest's custom worker APIs.

reactNative({ hotRuntime: true })

Leave it off unless you're specifically testing it.

Next: Third-Party Presets.