Skip to content

Upload SourceMap During Project Build

Guance currently provides a Vite plugin that allows you to easily upload SourceMap files from the corresponding directory during the Web project build process.

Note: Currently supports upload for Web applications.

Preparations

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

Vite

Install @cloudcare/vite-plugin-sourcemap

Using npm:

npm install @cloudcare/vite-plugin-sourcemap --save-dev

Using yarn:

yarn add @cloudcare/vite-plugin-sourcemap --dev

Using pnpm:

pnpm add @cloudcare/vite-plugin-sourcemap --save-dev

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

// vite.config.ts
import { defineConfig } from "vite"
import vue from "@vitejs/plugin-vue"
import { SourceMapUploadVitePlugin } from "@cloudcare/vite-plugin-sourcemap"
// https://vitejs.dev/config/
export default defineConfig({
  build: {
    sourcemap: true, // Source map generation must be turned on
  },
  plugins: [
    vue(),

    SourceMapUploadVitePlugin({
      applicationId: "xxxxx", // Guance application appid
      apiKey: "xxxxxxxx", // open apikey
      server: "https://console.xx-xxx.cn", // openapi address corresponding to the site
      filepaths: ["dist/"], // Directory to search, can be files or directories
      logLevel: "verbose", // Log printing level
      //   root: 'dist/', // Root directory corresponding to the relative directory to be uploaded
      env: "production", // Guance application env
      version: "1.0.0", // Guance application version
    }),
  ],
})

Sourcemap Plugin Options

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

  /**
   * openApi Key generated by the Guance platform. Refer to (https://docs.guance.com/en/management/api-key/open-api/#_1) for generation method.
   */
  apiKey: string

  /**
   * Guance platform OpenAPi service
   */
  server: string
  /**
   * applicationId corresponding to the Guance RUM application (required)
   */
  applicationId: string
  /**
   * version corresponding to the Guance RUM application (optional)
   */
  version?: string
  /**
   * env corresponding to the Guance RUM application (optional)
   */
  env?: string

  /**
   * Find all files matching the conditions, but do not upload files. Can be used for debugging.
   */
  dryRun?: boolean
  /**
   * Delete all found source map files after upload.
   */
  deleteAfterUpload?: boolean
  /**
   * If a source map cannot be matched to its generated file via its sourceMappingURL, attempt to match it by filename on the local disk.
   */
  matchSourcemapsByFilename: ?boolean

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

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

  /**
   * Set the directory from which relative paths should be calculated. The relative path of uploaded sourcemaps should be included in the path that caused the error. Therefore,
   * the meaning of this parameter is to control the relative directory for upload.
   * Default is the relative path from the execution directory to the search directory: path.relative(process.cwd(), filepath)
   */
  root?: string
  /**
   * Used during debugging, sets the level of logs generated.
   */
  logLevel?: "quiet" | "normal" | "verbose"
  /**
   * Whether to ignore errors on execution failure. This configuration ensures that errors do not interrupt the compilation process. Default is false, meaning errors are normally thrown by default.
   */
  warnOnFailure?: boolean
}

Sourcemap Visibility in Production Environment

In production environments, sourcemap files are typically not retained for security reasons. These files allow developers to map minified or compiled code back to the original source code, but if exposed publicly, they could reveal the application's internal logic, increasing security risks.

To handle sourcemaps securely, you can enable the deleteAfterUpload: true option when configuring the SourceMapUploadVitePlugin. This way, once the sourcemaps are uploaded to the server, they are immediately deleted from the local file system, ensuring they are not left behind in the production environment.

Furthermore, by setting build.sourcemap to "hidden" in vite.config.ts, 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" is enabled, you should also set matchSourcemapsByFilename: true in the SourceMapUploadVitePlugin plugin. This configuration ensures the plugin can identify and upload the corresponding Sourcemap files based on the JavaScript file names, even if there are no explicit references to them in the generated code.

Through these measures, you can effectively protect the security of your source code while maintaining the convenience of application debugging.

// vite.config.ts
import { defineConfig } from "vite"
import vue from "@vitejs/plugin-vue"
import { SourceMapUploadVitePlugin } from "@cloudcare/vite-plugin-sourcemap"
// https://vitejs.dev/config/
export default defineConfig({
  build: {
    sourcemap: "hidden", // Source map generation must be turned on
  },
  plugins: [
    vue(),

    SourceMapUploadVitePlugin({
      applicationId: "xxxxx", // Guance application appid
      apiKey: "xxxxxxxx", // open apikey
      server: "https://console.xxx-xxx.cn",
      filepaths: ["dist/"], // Directory to search, can be files or directories
      logLevel: "verbose", // Log printing level
      //   root: 'dist/', // Root directory corresponding to the relative directory to be uploaded
      env: "production", // Guance application env
      version: "1.0.0", // Guance application version
      deleteAfterUpload: true,
      matchSourcemapsByFilename: true,
    }),
  ],
})

How to DEBUG

If no corresponding Sourcemap is found during the process, you can run the build command by setting the environment variable DEBUG=sourcemap-upload or configuring logLevel: verbose to view detailed operation logs.

Notes

  • Node version > 16.

  • Notes on filepaths and root configuration:

There is an error in the console with one line: at SVGGElement.<anonymous> @ http://localhost:8000/js/chunk-vendors.732b3b98.js:1:93427. The relative path of the file causing the error is js/chunk-vendors.732b3b98.js. If the static directory for js files on the server is dist/js/*.js and dist/js/*.js.map, configure the plugin with filepaths: ['dist'].

If root is not configured, the default value is dist/. The final path of the Sourcemap file uploaded to the server would be dist/js/**.js.map. In this case, there would be a mismatch between the uploaded file directory path and the path that caused the error. Therefore, you should add the configuration root:'/' or root: '' to ensure the uploaded directory path is js/**.js.map.

Feedback

Is this page helpful? ×