Skip to content

Upload SourceMap During Project Build

TrueWatch currently provides a webpack plugin that allows you to easily upload SourceMap files for the corresponding directory during the build process of a Web project, eliminating the cumbersome manual upload process.

Note: Currently, only Web applications are supported.

Preparations

  1. Obtain the OpenApi domain address for the corresponding site;
  2. Obtain the required API KEY for OpenApi from TrueWatch here;
  3. Obtain the applicationId, env, and version information for the Web application on the TrueWatch platform. If there is no application, you need to create a new application;
  4. Preparations are complete.

Webpack

Install @cloudcare/webpack-plugin

 npm install @cloudcare/webpack-plugin --D

Modify the plugins option in the webpack.config.js file

// ....
const { SourceMapUploadWebpackPlugin } = require("@cloudcare/webpack-plugin")
module.exports = ({ mode }) => ({
  //.....
  devtool: "hidden-source-map",
  plugins: [
    //.....
    new SourceMapUploadWebpackPlugin({
      applicationId: "xxxxx", //  TrueWatch application appid
      apiKey: "xxxxxxxx", // open apikey
      server: "https://console.xxx-xxx.cn",
      filepaths: ["dist/"], // Directory to search, can be a file or directory
      logLevel: "verbose", // Log level, optional
      root: "dist/", // Directory to calculate relative paths, optional
      env: "production", // TrueWatch application env, optional
      version: "1.0.0", // TrueWatch application version, optional
    }),
  ],
})

SourceMap WebpackPlugin Configuration Explanation

interface Options {
  /**
   *
   * Files/directories to search for sourcemaps.
   * All files matching the "extensions" list but not matching the "ignore" list will be searched
   * for sourcemap JSON or `//#sourceMappingURL=` comments to find the generated file + sourcemap pair, then the sourcemap will be uploaded.
   */
  filepaths: Array<string> | string

  /**
   * OpenApi Key generated by the TrueWatch platform, refer to (https://docs.truewatch.com/management/api-key/open-api/#_1) for generation method
   */
  apiKey: string

  /**
   * OpenApi service of the TrueWatch platform
   */
  server: string
  /**
   * applicationId of the TrueWatch RUM application (required)
   */
  applicationId: string
  /**
   * version of the TrueWatch RUM application (optional)
   */
  version?: string
  /**
   * env of the TrueWatch RUM application (optional)
   */
  env?: string

  /**
   * Find all matching files but do not upload them, can be used for debugging
   */
  dryRun?: boolean

  /**
   * Delete all found sourcemap files after upload.
   */
  deleteAfterUpload?: boolean
  /**
   * If sourcemaps cannot be matched with their sourceMappingURL, try to match them by filename on the local disk
   */
  matchSourcemapsByFilename: ?boolean

  /**
   * List of file extensions to search in the directory
   * Default [".js", ".map"].
   */
  extensions?: Array<string>

  /**
   * List of files to ignore
   */
  ignore?: Array<string>

  /**
   * Directory to calculate relative paths. The relative path of the sourcemaps should be included in the path that generates the error, so
   * the purpose of this parameter is to control the relative directory of the upload
   * Default relative path from the execution directory to the search directory path.relative(process.cwd(), filepath)
   */
  root?: string
  /**
   * Log level for debugging
   */
  logLevel?: "quiet" | "normal" | "verbose"
  /**
   * Whether to ignore errors on failure, this configuration ensures that errors do not interrupt the build process. Default false, meaning errors will be thrown normally
   */
  warnOnFailure?: boolean
}

SourceMap Visibility in Production Environment

In production environments, SourceMap files are usually not retained for security reasons. These files allow developers to map minified or compiled code back to the original source code, but if made public, they could expose the internal logic of the application, increasing security risks.

To safely handle SourceMaps, you can enable the deleteAfterUpload: true option when configuring the SourceMapUploadWebpackPlugin. This ensures that once SourceMaps are uploaded to the server, they are immediately deleted from the local file system, preventing them from being left in the production environment.

Additionally, by setting Webpack's devtool to "hidden-source-map", you can generate SourceMaps without including any references to them in the JavaScript files. This prevents browsers from attempting to download and view the source code.

If "hidden-source-map" is enabled, you should also set matchSourcemapsByFilename: true in the SourceMapUploadWebpackPlugin. This configuration ensures that the plugin can identify and upload the corresponding SourceMap files based on the JavaScript file names, even if there are no explicit references in the generated code.

Through these measures, you can maintain the convenience of application debugging while effectively protecting the security of the source code.

 const { SourceMapUploadWebpackPlugin } = require('@cloudcare/webpack-plugin')
 = require('@cloudcare/webpack-plugin')

module.exports = {
  // Ensure that Webpack has been configured to output sourcemaps,
  // but without the `sourceMappingURL` references in buidl artifacts.
  devtool: 'hidden-source-map',
  // ...
  plugins: [
    // Enable our plugin to upload the sourcemaps once the build has completed.
    // This assumes NODE_ENV is how you distinguish production builds. If that
    // is not the case for you, you will have to tweak this logic.
    process.env.NODE_ENV === 'production'
      ? [
          new SourceMapUploadWebpackPlugin({
            ...
            deleteAfterUpload: true,
            matchSourcemapsByFilename: true,
          }),
        ]
      : [],
  ],
}

How to DEBUG

If the corresponding SourceMap is not found during the process, you can set the environment variable DEBUG=sourcemap-upload or configure logLevel: verbose to run the build command and view the detailed logs.

Notes

Node version > 10.13

filepaths and root Configuration Notes:

  1. In the Guance console, there is an error with the line at SVGGElement.<anonymous> @ http://localhost:8000/js/chunk-vendors.732b3b98.js:1:93427

  2. The relative path of the file causing the error is js/chunk-vendors.732b3b98.js

  3. If the js files are in the static directory on the server as dist/js/*.js dist/js/*.js.map

  4. Plugin configuration filepaths: ['dist']

  5. If root is not configured, the default value is dist/, and the sourcemap file path uploaded to the Guance server will be dist/js/**.js.map

  6. In this case, the uploaded file directory path will not match the error path, so you should add the configuration root:'/' or root: '' to ensure the uploaded directory path is js/**.js.map.