[RUM-11630] Support SVG in Session Replay

[cdn34dd]

What does this PR do?

This PR adds support for tracking SVG images in React Native Session Replay.

This PR is composed of 3 main components that work together to create a workflow that enables SVGs to be captured in Session Replay:

• New Babel Plugin Feature (@datadog/mobile-react-native-babel-plugin package)
• New Metro Plugin (@datadog/mobile-react-native-session-replay package)
• New CLI Utility (@datadog/mobile-react-native-babel-plugin package)

Babel Plugin

The Babel plugin feature is the core of this PR, containing most of the complexity. Its main responsibilities are to:

• Extract SVG nodes from the user's codebase during the build process
• Convert SVG nodes into a web-compliant format, which involves:
  • Updating tag and property names (e.g., strokeWidth → stroke-width)
  • Removing React Native-specific metadata
  • Converting styling information from React Native style objects into proper web SVG properties
  • Extracting transform properties from style objects
• Save extracted SVGs as optimized assets on the file system using SVGO optimization
• Properly identify SVG code nodes so they can be tracked by Session Replay on the native side

What kind of SVGs does the plugin handle?

To correctly identify and extract SVGs in a user's codebase, the plugin differentiates between three types of SVGs and handles each appropriately:

1. Inline SVGs

SVGs built directly in the codebase using elements from the react-native-svg library (e.g., <Svg>, <Path>, <Circle>). These require the most complex logic for full extraction and transformation.

Example:

<Svg width="100" height="100">
   <Circle cx="50" cy="50" r="45" fill="blue" />
</Svg>

2. External SVGs (Local)

SVGs loaded from the user's filesystem. These are typically already in web-compliant format, but the plugin needs to properly identify them in the user's code since they can be named anything.

Example:

import MyIllustration from './assets/illustration.svg';

<MyIllustration width="100" height="100" />

3. External SVGs (Remote)

SVGs loaded from external servers using the SvgUri component from react-native-svg.

Example:

 <SvgUri uri="https://example.com/icon.svg" />

What kind of SVGs do we still need to support?

The plugin currently handles direct usage of react-native-svg elements and loading SVG files directly. The main area for future expansion is adding support for popular SVG libraries built on top of react-native-svg, such as:

• react-native-feather
• iconoir-react-native
• @fluentui/react-native-icons

The groundwork to support these libraries is already in place, as the logic should be similar to handling local SVGs (treating library-generated SVGs as specialized local SVG cases).

Areas of Improvement

Some areas for future enhancement that didn't make it into this first release:

• Improved tracking of local SVGs when using aliased paths (e.g., @assets/icon.svg)
• Enhanced variable tracking for dynamically referenced SVG sources
• Extended style-to-SVG property conversion for edge cases where users set style properties directly on SVG elements
• Support for SVG data URLs. While the plugin itself supports it, the native Session Replay SDKs on Android and iOS still need to add support for it.
• Better error handling and reporting during the transformation process

All of these improvements are feasible with sufficient time allocation.

Metro Plugin

The Metro plugin (withSessionReplayAssetBundler) integrates with React Native's Metro bundler to automatically aggregate SVG assets during development and production builds.

Key responsibilities:

• Monitors the assets directory for new SVG files created by the Babel plugin during development
• Merges individual SVG files into a single optimized binary format (assets.bin) with an accompanying JSON index (assets.json) for efficient native lookup
• Automatically triggers asset aggregation on Metro events such as bundle_build_done and transformer_load_done
• Uses file watching with debouncing to efficiently handle rapid asset changes during hot reload

How it works:

The Metro plugin wraps the Metro config's reporter and watches for new .svg files in the
packages/react-native-session-replay/assets/ directory. When new SVG assets are detected (either from the Babel plugin or the CLI utility), it packs them into:

• assets.bin - A binary file containing all SVG data concatenated together
• assets.json - An index mapping SVG IDs to their byte offset and length in the binary file

This approach allows the native SDKs to efficiently load SVG assets by reading specific byte ranges from a single file rather than managing hundreds of individual files.

CLI Utility

The CLI utility (npx datadog-generate-sr-assets) provides a way to pre-generate all Session Replay SVG assets before native builds.

Key responsibilities:

• Scans the entire codebase for React components containing SVG elements
• Processes files through the Babel plugin with SVG tracking enabled
• Extracts and saves SVG assets to the Session Replay package's assets directory
• Generates the final assets.bin and assets.json files for native platform consumption

When to use it:

The CLI utility should be run after installing dependencies and before building iOS/Android apps:

After installing dependencies
yarn install

Generate SVG assets
npx datadog-generate-sr-assets

Then build native apps
cd ios && pod install && cd ..

This ensures that native asset references are available during the build process, particularly important for iOS where the
assets need to be included in the Xcode project.

What it does:

1. Clears any existing assets to ensure a fresh state
2. Scans all .js, .jsx, .ts, and .tsx files (excluding node_modules, test files, etc.)
3. Transforms each file using the Babel plugin to extract SVG assets
4. Merges all extracted SVGs into the binary format
5. Reports the number of assets generated

How does this all work together?

Here's the complete workflow for integrating SVG support in your React Native app:

1. Setup the Babel Plugin

Configure the Babel plugin in your babel.config.js to enable SVG tracking:

  module.exports = {
    presets: ['module:@react-native/babel-preset'],
    plugins: [
      [
        '@datadog/mobile-react-native-babel-plugin',
        {
          sessionReplay: {
             // This controls the SVG asset extraction activation
             // if set to false (default), no assets are extracted
            svgTracking: true
          }
        }
      ]
    ]
  };

2. Setup the Metro Plugin

Configure the Metro plugin in your metro.config.js to enable asset bundling:

const { withSessionReplayAssetBundler } = require('@datadog/mobile-react-native-session-replay/metro');

module.exports = withSessionReplayAssetBundler({ /* your existing Metro config */ });

3. Generate Assets Before Native Builds

Run the CLI utility after installing dependencies and before building native apps:

Install dependencies
yarn install

Generate Session Replay SVG assets
npx datadog-generate-sr-assets

Build iOS (if needed)
cd ios && pod install && cd ..

Now you can run your app
yarn ios
or
yarn android

4. Development Workflow

During development, the Metro plugin automatically handles new SVG assets created by the Babel plugin:

• Write your components with SVG elements from react-native-svg
• Metro bundler detects the new assets via the Babel plugin transformation
• The Metro plugin watches for new .svg files and automatically merges them
• Assets are immediately available for Session Replay recording

This ensures that SVGs are seamlessly captured in Session Replay without requiring manual asset management.

[marco-saia-datadog]

Amazing work 💯 the code looks good to me, and is very well documented, thank you! 🙌

I've left a few comments, some are minor nits and a couple are more important points to consider.

[OliviaShoup]

looks great. thanks for the update!

The base branch was changed.