Uploading SourceMap during Project Build¶

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

Note: Currently supports uploading for Web applications.

Preparation¶

Obtain the OpenApi domain address for the corresponding site;
In Guance obtain the required API KEY for OpenApi;
In Guance obtain the Web application's applicationId, env, and version information. If there is no application, you need to create a new one;
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 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's env
      version: '1.0.0', // Guance application's version
    }),
  ],
})

Sourcemap Plugin Options¶

interface Options {
  /**
   *
   * Files/directories to search for sourcemaps.
   * All files that match the "extensions configuration" list but do not match the "ignore configuration" will be searched for
   * sourcemap JSON or `//#sourceMappingURL=` comments, in order to find generated files + source mappings 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)
   */
  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 upload.
   */
  deleteAfterUpload?: boolean
  /**
   * If the source map cannot be matched with the generated file via sourceMappingURL, attempt to match it by filename on the local disk
   */
  matchSourcemapsByFilename: ?boolean

  /**
   * List of file extensions under the search 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, therefore
   * this parameter controls the uploaded relative directory
   * Default relative path from execution directory to search directory path.relative(process.cwd(), filepath)
   */
  root?: string
  /**
   * Used during debugging, determines the log level produced
   */
  logLevel?: 'quiet' | 'normal' | 'verbose'
}

Is Sourcemap Visible in Production?¶

In production environments, for security reasons, systems typically do not retain sourcemap files. These files allow developers to map compressed or compiled code back to the original source code, but if made public, they may expose the internal logic of the application, increasing security risks.

To handle sourcemaps securely, you can enable the deleteAfterUpload: true option when configuring GuanceSourceMapUploadVitePlugin. This way, once the sourcemap is uploaded to the server, it will immediately be deleted from the local file system, ensuring that it does 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 to be uploaded
      env: 'production', // Guance application's env
      version: '1.0.0', // Guance application's version
      deleteAfterUpload: true,
      matchSourcemapsByFilename: true,
    }),
  ],
})

How to DEBUG¶

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

Precautions¶

Node version > 16;
Notes on filepaths and root configurations:

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

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