/dt-setup-react-native

name: dt-setup-react-native
license: Apache-2.0
description: >-
  Integrate the Dynatrace React Native Plugin into a React Native or Expo project —
  dependency setup, dynatrace.config.js, Babel registration, npx instrumentation,
  navigation tracking, user privacy options, and verification. Handles both bare React Native
  and Expo (babel-preset-expo) Babel configuration automatically.
  Trigger: "add Dynatrace to React Native", "React Native plugin setup", "instrument React Native app",
  "integrate Dynatrace RN", "mobile observability React Native", "react-native-plugin",
  "dynatrace react native", "add Dynatrace to Expo", "instrument Expo app", "Dynatrace Expo setup".
  Do NOT use for: querying RN RUM data (use dt-obs-frontends), non-React Native mobile setups,
  or Dynatrace server-side configuration.

Dynatrace React Native Plugin Integration Skill

Prerequisites

• Node.js 16.0+ and npm available on `PATH`
• An existing React Native project (v0.68+) or Expo project (v45+) with a `package.json` at the project root
• `android/` and `ios/` platform folders present (Expo managed workflow requires `npx expo prebuild` first)
• A Dynatrace environment with access to Experience Vitals (to obtain `applicationId` and `beaconUrl`, or to download `dynatrace.config.js`)
• Console access to Experience Vitals → Mobile to configure app settings (Data Privacy, Enablement and Cost Control)
• macOS with CocoaPods for iOS builds

Work through the steps below in order, interacting with the user at each decision point. Read actual project files before suggesting changes — do not assume the current state.

Step 1 — Check for existing `dynatrace.config.js`

Before asking the user anything, check whether `dynatrace.config.js` exists at the project root.

• **File exists:** Read it, show the `applicationId` and `beaconUrl`, and confirm they match the target environment. If correct, run the `userOptIn` check below and skip to Step 3 (config is already present — Step 2 is not needed).
• **File does not exist:** Proceed to Step 2.

**`userOptIn` check:**

Inspect the file for `userOptIn` (Android block) and `DTXUserOptIn` (iOS block).

• **Present on both platforms:** Trust the value as-is. If `true`, flag Step 9. If `false`, skip Step 9.
• **Absent from either platform:** Ask the user: **"Do you have User Opt-In mode enabled or disabled?"** (If unsure: Experience Vitals → Mobile → [Your App] → Settings → Data Privacy.) Add the missing value to the relevant platform(s), then flag Step 9 if the final value is `true`.

Step 2 — Obtain `dynatrace.config.js` (only if Step 1 found no file)

Ask the user which approach they prefer:

**Option A — Download from console (recommended):**

1. Open their Dynatrace environment 1. Navigate to: Experience Vitals → New Frontend → Mobile 1. Enter app name and choose **React Native** as the platform 1. On the **Select capability and settings** screen, configure monitoring features (crash reporting, user action monitoring, etc.) 1. Download `dynatrace.config.js` and place it at the project root (same level as `package.json`)

Once the file is in place, apply the `userOptIn` check from Step 1 and flag Step 9 if needed.

**Option B — Provide credentials manually:** Read `references/config-js.md` for the full template and conditional blocks. Collect all required values from the user before creating any files, then apply the `userOptIn` check and flag Step 9 if needed.

Step 3 — Install the plugin

Read `package.json` first.

• **Not present:** Run:

  npm install @dynatrace/react-native-plugin

• **Already under `dependencies`:** No change needed.
• **Under `devDependencies`:** Remove it and run `npm install @dynatrace/react-native-plugin`. The plugin is required at runtime including in release builds.

Note: `npm install` alphabetically sorts the `dependencies` object in `package.json`. Existing entries may appear reordered after this step — this is expected npm behavior, not an error.

Step 4 — Install iOS pods (macOS only)

If on macOS and targeting iOS, run:

cd ios && pod install && cd ..

Confirm success before continuing. CocoaPods must be installed (`gem install cocoapods` if missing).

Step 5 — Register Babel plugin in `babel.config.js`

Read `babel.config.js`. Append `BabelPluginDynatrace` to the `plugins` array, **just before** `react-native-reanimated/plugin` if that plugin is present (reanimated must always be last):

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    // ... existing plugins ...
    '@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace',
    // react-native-reanimated/plugin goes here if present — must stay last
  ],
};

• If the plugins array already contains `'@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace'`: skip this step.
• If `useLegacyJscodeshift: true` is set in `dynatrace.config.js`: the Babel plugin is already applied internally — skip this step.
• If the project already configures `metro.config.js` with `babelTransformerPath: '@dynatrace/react-native-plugin/lib/dynatrace-transformer'`: that is the legacy Metro transformer approach — auto-instrumentation is already handled; skip this step and Step 6.

Common mistakes to flag and correct:

• Placing the plugin in `presets` instead of `plugins`
• Placing `BabelPluginDynatrace` after `react-native-reanimated/plugin` — reanimated must always be the absolute last plugin

Step 6 — Register JSX runtime in `babel.config.js`

Read `babel.config.js` and determine which preset the project uses — this controls how the JSX runtime is registered.

Expo (`babel-preset-expo`)

If `babel-preset-expo` appears in `presets`, set `jsxImportSource` **on the preset itself**. Do not add a separate `@babel/plugin-transform-react-jsx` plugin — Expo's preset already owns the JSX transform, and stacking a second JSX plugin over it breaks the instrumentation.

module.export