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)
  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
  // presets — omitted on purpose: leaving it out auto-detects your installed
  // libraries. Passing an array uses ONLY that array, so `presets: []` means none.
})

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. To test both platforms, run them as separate Vitest projects with one plugin instance each. (Under the mock engine only, setPlatform can also switch per-test at runtime; the native engine fixes the platform when the module graph loads.)

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:

Providing this option replaces auto-detection

When presets is present, only the presets in the array are used — auto-detection does not run. presets: [] therefore disables every preset, including ones your app depends on. Omit the option entirely to keep auto-detection.

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

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

mocks

Mock engine only

mocks merges overrides into the mock's export table, so it only applies with engine: 'mock' — the native engine runs the real react-native module and throws a configuration error if mocks is set. Use vi.mock() in a setup file or mockNativeModule instead.

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 })

It can dramatically cut the per-file cost on large suites, but because React Native stays resident, suites that lean on deep resident-RN-internal state (for example heavy cross-file Animated usage) can see cross-file interference they wouldn't under the default per-file isolation. The tell is a test that passes alone but fails after other files. See Hot runtime for when it helps, the known limitation, and worker recycling.

Next: Third-Party Presets.