Application Real-Time Monitoring Service:Automatically upload source maps with the web and H5 plugin

Webpack

1. Install the RUM Webpack build tool plugin npm package.

   npm install -D @arms/rum-webpack-plugin

2. Integrate and configure the Webpack plugin.

   For production builds, use hidden-source-map to avoid exposing the source map URL in the JavaScript output.

   const { rumWebpackPlugin } = require('@arms/rum-webpack-plugin');
   
   module.exports = {
     mode: 'production',
     devtool: 'hidden-source-map',
     plugins: [
       rumWebpackPlugin({
         workspace: 'your-workspace',
         serviceId: 'your-rum-service-id',
         version: 'your-release-version',
         region: 'cn-hangzhou',
         accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
         accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
         stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
         clearSourceMap: true,
       }),
     ],
   };

   Webpack skips source map processing and upload when mode === 'development' or NODE_ENV === 'development'. Use a non-development build to upload production source maps.

Vite

1. Install the RUM Vite build tool plugin npm package.

   npm install -D @arms/rum-vite-plugin

2. Integrate and configure the Vite plugin.

   import { defineConfig } from 'vite';
   import { rumVitePlugin } from '@arms/rum-vite-plugin';
   
   export default defineConfig({
     build: {
       sourcemap: true,
     },
     plugins: [
       rumVitePlugin({
         workspace: 'your-workspace',
         serviceId: 'your-rum-service-id',
         version: 'your-release-version',
         region: 'cn-hangzhou',
         accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
         accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
         stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
         clearSourceMap: true,
       }),
     ],
   });

   build.sourcemap can be set to true or 'hidden'. Do not set it to 'inline'.

Check source map files

When clearSourceMap: false, open a .map file in the build output directory. A correctly formatted debugId at the top level indicates that injection succeeded. Example:

{
  "version": 3,
  "file": "index.js",
  "sources": ["webpack://app/src/index.ts"],
  "sourcesContent": ["throw new Error('test');"],
  "mappings": "AAAA",
  "debugId": "e4f083d6-b8d8-4cae-a0ea-16f2e83a6be1"
}

sourcesContent must be present and non-empty. If it is missing or empty, RUM may only be able to restore the file location and cannot display the source code context.

Check the browser runtime

Open the deployed page and run the following in the browser console:

window._armsRumDebugIds;

If the returned object contains UUID mappings, the JavaScript files on the current page have registered a debugId. The plugin also registers the debugId in globalThis, self, global, document.defaultView, and accessible parent/top windows to support iframe and micro-frontend scenarios.

Check upload results

On the File Management page of your RUM application, verify that:

• Source map files have appeared.

• The file version matches the version configured in the plugin.

• The UUID matches the debugId in the build output.

Build logs report that source map files cannot be found

Check whether your build tool is generating separate .map files. Do not use inline or eval source maps, and verify that the filenames and paths of JavaScript files and .map files have not been modified by post-processing scripts.

Upload succeeded but the exception details page does not display source code

Check in sequence:

1. Does the .map file contain a non-empty sourcesContent?

2. Does the debugId in the source map match the UUID reported in the exception stack trace?

3. Do workspace, serviceId, version, and region match your target RUM application?

4. Does the uploaded file appear on the File Management page of the target application?

Webpack is not uploading files

Confirm that neither mode nor NODE_ENV is set to development, and verify that external source map files are being generated.

Can I use a custom OSS bucket?

No. The upload endpoint and form parameters are returned by the OpenAPI. The plugin does not expose bucket configuration.

How do I prevent source maps from being deployed to the public internet?

For Webpack, use hidden-source-map. Also set clearSourceMap: true. The plugin deletes the corresponding local .map file after each successful upload.

I see an error that the current Node.js version does not support certain features

Upgrade your build environment to Node.js 20 LTS or Node.js 22 and later. The dependencies used by the Vite plugin do not support Node.js 18 or 21.

A source map file exceeds the size limit

A single source map file cannot exceed 50 MiB. You can reduce the file size through code splitting, reducing inline source content, or adjusting your build configuration. You must retain sufficient sourcesContent to display source code context.

Source map auto-matching fails when chunk URLs contain parentheses

When webpack chunk URLs contain special characters such as parentheses — for example, the route group format used by Next.js App Router (/app/(groupName)/page/) — ARMS cannot correctly parse the UUID from the binary_images field in the reported JS error. As a result, automatic source map matching fails. Chunk URLs without parentheses in the same exception are parsed normally.

This is a known ARMS parsing limitation. To avoid this issue, configure webpack to exclude parentheses from chunk naming paths. For example, rename Next.js route group directories to avoid the (groupName) format.