Uploading SourceMap During Project Build¶

Guance currently provides a Vite plugin that can easily upload the corresponding directory's SourceMap files during the build process of Web projects, solving the cumbersome manual upload process.

Note: Currently supports uploading for Web applications.

Preparation¶

Obtain the OpenApi domain address for the corresponding site;
Obtain the required API KEY for OpenApi from Guance here;
Obtain the applicationId, env, and version information for the Web application on the Guance platform. If you do not have an application, you need to create a new application;
Preparation 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 { GuanceSourceMapUploadVitePlugin } from '@cloudcare/vite-plugin-sourcemap'
// https://vitejs.dev/config/
export default defineConfig({
  build: {
    sourcemap: true, // Source map generation must be turned on
  },
  plugins: [
    vue(),

    // Put the Sentry vite plugin after all other plugins
    GuanceSourceMapUploadVitePlugin({
      applicationId: 'xxxxx', // Guance application appid
      apiKey: 'xxxxxxxx', // open apikey
      server: 'https://console.guance-xxx.cn',
      filepaths: ['dist/'], // Directories or files to search
      logLevel: 'verbose', // Log print 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 {
  /**
   *
   * Files/directories 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 generated file + source map pairs, which will then be uploaded.
   */
  filepaths: Array<string> | string

  /**
   * OpenApi Key generated by the Guance platform, refer to (https://docs.guance.com/management/api-key/open-api/#_1)
   */
  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
  /**
   * Environment corresponding to the Guance RUM application (optional)
   */
  env?: string

  /**
   * Find all eligible files without uploading them, useful for debugging
   */
  dryRun?: boolean
  /**
   * Delete all found source map files after uploading.
   */
  deleteAfterUpload?: boolean
  /**
   * If the source map cannot be matched with the generated file via sourceMappingURL, try to match by filename on the local disk
   */
  matchSourcemapsByFilename?: boolean

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

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

  /**
   * Set the directory where relative paths should be calculated. The relative path of the uploaded sourcemaps should be included in the error path, so
   * this parameter controls 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 for debugging, sets the log level
   */
  logLevel?: 'quiet' | 'normal' | 'verbose'
}

Visibility of Sourcemap in Production¶

In production environments, for security reasons, we typically do not retain sourcemap files. These files allow developers to map minified or compiled code back to the original source code, but if exposed publicly, they may reveal the internal logic of the application, increasing security risks.

To handle sourcemaps securely, you can enable the deleteAfterUpload: true option when configuring GuanceSourceMapUploadVitePlugin. This ensures that once the sourcemap is uploaded to the server, it is immediately deleted from the local file system, preventing it from lingering in the production environment.

Additionally, by setting build.sourcemap to "hidden" in vite.config.ts, you can generate sourcemaps without including any references to them in 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 GuanceSourceMapUploadVitePlugin configuration. This ensures that the plugin can identify and upload the corresponding sourcemap files based on the names of the JavaScript files, even if they are not explicitly referenced in the generated code.

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

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

    // Put the Sentry vite plugin after all other plugins
    GuanceSourceMapUploadVitePlugin({
      applicationId: 'xxxxx', // Guance application appid
      apiKey: 'xxxxxxxx', // open apikey
      server: 'https://console.guance-xxx.cn',
      filepaths: ['dist/'], // Directories or files to search
      logLevel: 'verbose', // Log print 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 the corresponding sourcemap is not found during runtime, you can set the environment variable DEBUG=guance:sourcemap-upload or configure logLevel: verbose when running the build command to view detailed logs.

Precautions¶

Node Version `> 16`¶

Notes on `filepaths` and `root` Configuration:¶

In the Guance console, there is an error 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 dist/js/*.js.map
Plugin configuration filepaths: ['dist']
Without configuring root, the default value is dist/, and the final uploaded sourcemap file path to the Guance server is dist/js/**.js.map
In this case, the uploaded file directory path does not match the error path, so you should add the configuration root:'/' or root: '' to ensure the upload directory path is js/**.js.map.