Uploading SourceMap During Project Build¶

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

Note: Currently supports uploading for Web applications.

Preparation¶

Obtain the OpenApi domain address for the corresponding site;
In Guance obtain the required OpenApi API KEY;
On the Guance platform, obtain the Web application's applicationId, env, and version information. If there is no 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 vite.config.js file's plugins option

// 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 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 for upload
      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, so as to find generated files + source maps pairs, then source maps will be uploaded.
   */
  filepaths: Array<string> | string

  /**
   * The 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 eligible files without uploading them, useful for debugging
   */
  dryRun?: boolean
  /**
   * Delete all found source map files after upload.
   */
  deleteAfterUpload?: boolean
  /**
   * If source maps cannot be matched with their generated files through sourceMappingURL, try to match by filename on the local disk
   */
  matchSourcemapsByFilename: ?boolean

  /**
   * List of file extensions to search under directories
   * 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 uploaded sourcemaps should be included in the error path, thus
   * this parameter controls the relative directory for upload
   * Default relative path from execution directory to search directory path.relative(process.cwd(), filepath)
   */
  root?: string
  /**
   * Used for debugging, determines the level of logs produced
   */
  logLevel?: 'quiet' | 'normal' | 'verbose'
}

Visibility of Sourcemap in Production Environment¶

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

To securely handle sourcemaps, you can enable the deleteAfterUpload: true option when configuring GuanceSourceMapUploadVitePlugin. This way, once the sourcemap is uploaded to the server, it will be immediately deleted from the local file system, ensuring that they do not remain in the production environment.

Additionally, by setting build.sourcemap in vite.config.ts to "hidden", 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 plugin. This configuration ensures that the plugin can identify and upload the corresponding sourcemap files based on the names of 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 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 for upload
      env: 'production', // Guance application env
      version: '1.0.0', // Guance application version
      deleteAfterUpload: true,
      matchSourcemapsByFilename: true,
    }),
  ],
})

How to DEBUG¶

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

Precautions¶

Node Version `> 16`¶

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

There is an error line in the Guance console 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 js files are in the static directory on the server as dist/js/*.js dist/js/*.js.map.
Plugin configuration filepaths: ['dist'].
If root is not configured, the default value is dist/, and the final sourcemap file path uploaded to the Guance server is dist/js/**.js.map.
In this case, the uploaded file directory path does not match the error-generating path, so you should add the configuration root:'/' or root: '', ensuring the upload directory path is js/**.js.map.