@grafana/faro-metro-plugin

中文文档
0.5.4发布于 2026/11/06Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 11.2万

Upload React Native (Metro + Hermes) source maps to the Faro source map API and inject Faro bundle id preamble

原始使用文档
文档目录13 节
  1. End-to-end flow
  2. Installation
  3. Metro configuration
  4. Environment variables
  5. When Hermes skips native precompile
  6. Hermes modes
  7. Android
  8. With @grafana/faro-react-native
  9. Without @grafana/faro-react-native
  10. iOS upload
  11. Optional: sourceMapFile
  12. Sanity check: react-native bundle
  13. Grafana UI

Faro source maps — Metro (React Native)

This package configures Metro so release bundles work end-to-end with Grafana Frontend Observability:

  1. Bundle id preamble — Same idea as @grafana/faro-webpack-plugin: a small snippet at the top of the JS bundle sets meta.app.bundleId so it matches the source map record in @grafana/faro-react-native / @grafana/faro-web-sdk.

  2. Source map shape — Metro emits the packager map in the form Hermes precompile, Hermes interpreter, or JSC expects (see Hermes modes).

  3. Upload — Happens after the native pipeline produces the composed map (hermesc + compose-source-maps.js). Metro does not upload; the composed map is the one the collector uses for symbolication.


End-to-end flow

StepWhere
1Install @grafana/faro-metro-plugin and wrap metro.config.js with withFaroConfig.
2Install and initialise @grafana/faro-react-native with the same app.name as appName in Metro options.
3For release builds, export FARO_BUNDLE_ID and FARO_SOURCEMAP_* (see Environment variables).
4
  • Android: Upload runs from Gradle after the composed map is produced (see Android).
  • iOS: Upload after the composed map exists via Xcode automation that calls this package’s bin/ helpers (Release-only), or manually with faro-cli metro upload (see iOS upload).

Symbolication runs server-side in the Faro collector: it loads the map by bundleId from the source map API and resolves stack frames.


Installation

npm install --save-dev @grafana/faro-metro-plugin
# or
yarn add --dev @grafana/faro-metro-plugin

Also add @grafana/faro-react-native as a runtime dependency if you use the standard Android Gradle wiring.


Metro configuration

In metro.config.js:

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const withFaroConfig = require('@grafana/faro-metro-plugin').default;

const faroOpts = {
  appName: 'MyApp',
  endpoint: 'https://your-collector.example.com/api/v1',
  appId: 'your-app-id',
  stackId: 'your-stack-id',
  apiKey: process.env.FARO_SOURCEMAP_API_KEY,
  bundleId: process.env.FARO_BUNDLE_ID,
  verbose: true,
};

module.exports = mergeConfig(getDefaultConfig(__dirname), withFaroConfig({}, faroOpts));

Metro uses: appName, bundleId (or FARO_BUNDLE_ID), optional hermes, sourceMapFile, skipUpload, verbose.
The shared option shape also requires endpoint, appId, stackId, apiKey; keep them aligned with Frontend Observability → Settings → Source Maps and with the same values you pass into faro-cli metro upload or your Gradle / Xcode automation.

When using @sentry/react-native, wrap Sentry outside and Faro inside so the preamble stays first, for example:

mergeConfig(getDefaultConfig(__dirname), withSentryConfig(withFaroConfig({}, faroOpts))) — check Sentry’s docs for your RN version.


Environment variables

VariablePurpose
FARO_SOURCEMAP_API_KEYBearer token for the upload HTTP request (Gradle, Xcode automation, or CLI).
FARO_SOURCEMAP_ENDPOINTCollector API base URL (Gradle, Xcode automation, or CLI).
FARO_SOURCEMAP_APP_IDApp id segment in the upload URL (Gradle, Xcode automation, or CLI).
FARO_SOURCEMAP_STACK_IDStack id for the upload (Gradle, Xcode automation, or CLI).
FARO_BUNDLE_IDRelease: Stable build id (commit SHA, CI build number, …). Must match what Metro baked into the bundle. Omit for local dev.
FARO_SKIP_SOURCEMAP_UPLOADIf 1 or true, native upload steps skip while still building; preamble and map shaping unchanged. Also participates in dev bundle-id behaviour when no explicit id is set.
FARO_DISABLE_HERMES_PRECOMPILERare. Only if Metro runs with dev: false but the JS you ship never goes through the usual native hermesc + compose-source-maps.js step (see When Hermes skips native precompile). Dev does not need this—Metro dev: true is detected automatically. Normal Android/iOS release builds must leave this unset.

skipUpload: true, NODE_ENV=development, Metro dev: true, and FARO_SKIP_SOURCEMAP_UPLOAD affect placeholder bundle ids and whether native upload steps run; none of them perform upload from Metro.

When Hermes skips native precompile

Set FARO_DISABLE_HERMES_PRECOMPILE only in the situations below. Everyone else should omit it.

Default: leave it unset. That matches stock React Native: e.g. Android ./gradlew assembleRelease (or your project’s equivalent that runs bundleReleaseJsAndAssets and the RN Hermes/map steps) and iOS Release archive—those pipelines always precompile Hermes bytecode and compose maps after Metro.

Metro already chooses the right map shape for development (dev: true → Hermes “runtime” / flattened map). You do not need this variable for npx react-native start or day-to-day debugging.

Set the variable (usually only in CI or a dedicated script) when all of the following are true:

  1. You produce a production bundle with Metro dev: false (same as a release JS bundle).
  2. That bundle is loaded in Hermes in a way where stack traces look like dev Hermes (line 1 + UTF-8 byte column in the JS source text)—not like a map meant for the composed Hermes bytecode pipeline.
  3. Your pipeline does not run the standard post-Metro hermesc + compose-source-maps.js flow that assembleRelease / a typical Xcode Release build performs.

Concrete-style example (illustrative, not a single official command): a team runs only npx react-native bundle --platform android --dev false … in CI, ships index.android.bundle + .map through a custom native shell or distribution path, and never invokes Gradle’s release Hermes steps that merge Metro’s map with the bytecode map. Production crashes then behave like Hermes-on-raw-bundle symbolication; setting FARO_DISABLE_HERMES_PRECOMPILE=1 for that Metro job makes the emitted map match those stacks. The same app built with a normal ./gradlew assembleRelease must not set this—doing so can break compose-source-maps (multi-line packager map is required there).

Who sets it: not every developer—only the maintainer of the non-standard build defines it once (e.g. export in the CI job or script that runs the odd Metro-only release bundle).


Hermes modes

How Metro output is shaped depends on the scenario. The plugin always injects the Faro bundle id line at the top of the JS; it reshapes the source map only when the engine reports positions in a different coordinate system.

ScenarioWhat the plugin is doing (plain language)What you end up with
Release, Hermes (normal RN)Tags the bundle with a Faro id; lightly fixes the map so that extra line doesn’t break positions; leaves a normal multi-line map so the native build can still merge Metro + Hermes maps.JS with id + map ready for the native Hermes/compose step; production symbolication usually uses the final map from that pipeline.
Dev, Metro + HermesTags the bundle; rewrites the map so Hermes dev errors (one line + byte offset) can still be mapped back to source.JS with id + flattened map that matches live dev stacks.
JSC onlyTags the bundle; only shifts line numbers for that id line—no Hermes-specific map rewrite.JS with id + classic line/column map.

We always label the bundle; we only “reshape” the source map when the JavaScript engine reports crashes in a different coordinate system (Hermes in dev).

Implementation (reference): internal mode names and triggers:

ModeWhenMap shape from Metro
precompileddev: false, Hermes enabled (hermes !== false), FARO_DISABLE_HERMES_PRECOMPILE unset — typical Android/iOS releaseMulti-line map with +1 line shift on generated lines
runtimedev: true or FARO_DISABLE_HERMES_PRECOMPILE setSingle-line mappings with UTF-8 byte offsets on line 1
jschermes: false in plugin optionsMulti-line map with +1 line shift

For precompiled, Xcode/Gradle run compose-source-maps.js after Metro. That step needs the multi-line packager map; flattening it at Metro would break the composed map (sources empty) and symbolication.

Upload always happens after compose: Gradle on Android, Xcode automation calling this package’s bin/ on iOS (Release-only), or faro-cli metro upload where you drive uploads yourself.


Android

With @grafana/faro-react-native

  1. Dependencies: @grafana/faro-react-native (app) and @grafana/faro-metro-plugin (dev).
  2. Configure Metro as in Metro configuration.
  3. Export FARO_BUNDLE_ID and all FARO_SOURCEMAP_* vars before release builds.
  4. Run a normal release workflow (yarn android --mode=release, installRelease, assembleRelease, bundleRelease, …).

React Native autolinks the SDK’s Android library. Its android/build.gradle registers faroUploadComposedSourceMapAndroidRelease on your :app project and attaches it as a finaliser of bundleReleaseJsAndAssets / createBundleReleaseJsAndAssets after gradle.projectsEvaluated.

You do not edit android/app/build.gradle for this path.

The task runs node_modules/@grafana/faro-metro-plugin/bin/faro-upload-source-map.js, which invokes faro-cli metro upload with --map pointing at:

android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

and passes --bundle-id, --endpoint, --app-id, --stack-id, --api-key from the Gradle environment.

If the shim is missing, the composed map does not exist, any required env var is missing, or FARO_SKIP_SOURCEMAP_UPLOAD is set, the task logs and skips — it does not fail the build.

Without @grafana/faro-react-native

Use the same Gradle behaviour by applying this package’s script from android/app/build.gradle:

apply from: file("../../node_modules/@grafana/faro-metro-plugin/android/source-map-upload.gradle")

Adjust the relative path if your node_modules layout differs. Export the same env vars as above before release builds.


iOS upload

Layout (same idea as Android): Anything executable lives in @grafana/faro-metro-plugin under bin/ (for example the existing faro-upload-source-map entry that forwards to faro-cli metro upload). @grafana/faro-react-native should only wire Xcode — for example a React Native scriptPhases hook — that execs those paths under node_modules/@grafana/faro-metro-plugin/bin/, not ship duplicate scripts inside the SDK.

Release-only: That Xcode step must no-op on non-Release configurations (inspect Xcode’s CONFIGURATION / equivalent). Debug and simulator-oriented builds stay quiet and never call the upload CLI.

Manual / CI (when nothing uploads the map for you): Use this if the automatic path does not run—for example you have not wired the Android Gradle task or an Xcode Release script phase that calls node_modules/@grafana/faro-metro-plugin/bin/, upload steps are skipped (FARO_SKIP_SOURCEMAP_UPLOAD, missing env vars), or CI builds the composed map in a job without those hooks. Invoke faro-cli metro upload after Release produces the composed map:

npx faro-cli metro upload \
  --map "$BUILD_DIR/main.jsbundle.map" \
  --endpoint "$FARO_SOURCEMAP_ENDPOINT" \
  --app-id "$FARO_SOURCEMAP_APP_ID" \
  --stack-id "$FARO_SOURCEMAP_STACK_ID" \
  --api-key "$FARO_SOURCEMAP_API_KEY" \
  --bundle-id "$FARO_BUNDLE_ID"

Android the same way—only when Gradle is not already running the upload finaliser (or you need a standalone CI step using the same flags as Gradle):

npx faro-cli metro upload \
  --map android/app/build/generated/sourcemaps/react/release/index.android.bundle.map \
  --endpoint "$FARO_SOURCEMAP_ENDPOINT" \
  --app-id "$FARO_SOURCEMAP_APP_ID" \
  --stack-id "$FARO_SOURCEMAP_STACK_ID" \
  --api-key "$FARO_SOURCEMAP_API_KEY" \
  --bundle-id "$FARO_BUNDLE_ID"

Flags accept the matching FARO_* env fallbacks where documented in @grafana/faro-cli.

The CLI rejects composed maps with empty sources (usually wrong Metro map shape for compose-source-maps.js) and exits with code 3.


Optional: sourceMapFile

Metro writes the map’s file field from this basename (default bundle.js). Align with releaseBundleFilename in @grafana/faro-react-native if you change it.


Sanity check: react-native bundle

Match appName, FARO_BUNDLE_ID, and upload settings with CI.

Android

npx react-native bundle \
  --platform android \
  --dev false \
  --minify true \
  --entry-file index.js \
  --bundle-output dist/android-release/index.android.bundle \
  --sourcemap-output dist/android-release/index.android.bundle.map \
  --assets-dest dist/android-release/res

iOS — Set sourceMapFile to main.jsbundle for this run so the map’s file matches stacks and releaseBundleFilename:

FARO_PLATFORM=ios npx react-native bundle \
  --platform ios \
  --dev false \
  --minify true \
  --entry-file index.js \
  --bundle-output dist/ios-release/main.jsbundle \
  --sourcemap-output dist/ios-release/main.jsbundle.map \
  --assets-dest dist/ios-release/assets

Check: Bundle starts with __faroBundleId_<appName>; .map is JSON version 3, non-empty sources, file matching your bundle basename.


Grafana UI

In Frontend Observability → your app → Settings, open Source Maps for endpoint, appId, stackId, and Metro-oriented snippets.

版本与发布记录

@grafana/faro-metro-plugin 共发布 10 个版本,首次发布于 2026/05/20;过去 12 个月发布了 10 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.5.4latest2026/11/0610 天前
0.5.32026/10/2721 天前
0.5.22026/10/151 个月前
0.5.12026/10/061 个月前
0.5.02026/09/221 个月前
0.4.02026/08/292 个月前

关于 @grafana/faro-metro-plugin 的常见问题

@grafana/faro-metro-plugin 是什么?

Upload React Native (Metro + Hermes) source maps to the Faro source map API and inject Faro bundle id preamble

如何安装 @grafana/faro-metro-plugin?

在项目目录运行 npm install @grafana/faro-metro-plugin,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:metro(>=0.81.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 faro-upload-source-map,可以用 npx faro-upload-source-map 直接运行。

@grafana/faro-metro-plugin 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grafana/faro-metro-plugin 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@grafana/faro-metro-plugin 可以商用吗?

@grafana/faro-metro-plugin 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/faro-metro-plugin 的下载量有多少?

根据 npm 官方下载统计,@grafana/faro-metro-plugin 在 2026/10/17 – 2026/11/15 这 30 天内被下载 111,667 次,日均约 3,722 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/faro-metro-plugin 还在维护吗?

最新版本 0.5.4 发布于 2026/11/06(10 天前);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/05/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。