Uploading SourceMap During Project Build¶
Guance currently provides a webpack
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 theOpenApi
from Guance here; - Obtain the
applicationId
,env
, andversion
information for the Web application on the Guance platform. If there is no application, you need to create a new application; - Preparation complete.
Webpack¶
Install @cloudcare/webpack-plugin
Modify the plugins
option in the webpack.config.js
file
// ....
const { GuanceSourceMapUploadWebpackPlugin } = require('@cloudcare/webpack-plugin')
module.exports = ({ mode }) => ({
//.....
devtool: 'hidden-source-map',
plugins: [
//.....
new GuanceSourceMapUploadWebpackPlugin({
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 level, optional
root: 'dist/', // Directory for calculating relative paths, optional
env: 'production', // Guance application env, optional
version: '1.0.0', // Guance application version, optional
}),
],
})
Configuration Explanation for SourceMap WebpackPlugin¶
interface Options {
/**
*
* Files/directories to search for sourcemaps.
* All files that match the list of "extensions" configuration but do not match the "ignore" configuration will be searched
* for sourcemap JSON or `//#sourceMappingURL=` comments to find generated files + source map pairs, which will then be uploaded.
*/
filepaths: Array<string> | string
/**
* OpenApi Key generated by the Guance platform, see (https://docs.guance.com/management/api-key/open-api/#_1) for generation method
*/
apiKey: string
/**
* Guance OpenApi service
*/
server: string
/**
* ApplicationId (required) for the Guance RUM application
*/
applicationId: string
/**
* Version (optional) for the Guance RUM application
*/
version?: string
/**
* Env (optional) for the Guance RUM application
*/
env?: string
/**
* Search all matching files without uploading them, useful for debugging
*/
dryRun?: boolean
/**
* Delete all found source map files after upload.
*/
deleteAfterUpload?: boolean
/**
* Attempt to match source maps by filename on local disk if sourceMappingURL cannot match with the generated file
*/
matchSourcemapsByFilename?: boolean
/**
* List of file extensions to search within directories
* Default [".js", ".map"].
*/
extensions?: Array<string>
/**
* List of files to ignore
*/
ignore?: Array<string>
/**
* Directory for calculating relative paths. The relative path of uploaded sourcemaps should be included in the error path,
* so this parameter controls the relative directory of uploads.
* Default is the relative path from the execution directory to the search directory `path.relative(process.cwd(), filepath)`
*/
root?: string
/**
* Debugging log level
*/
logLevel?: 'quiet' | 'normal' | 'verbose'
}
Visibility of SourceMap in Production Environment¶
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 safely handle SourceMaps, you can enable the deleteAfterUpload: true
option when configuring GuanceSourceMapUploadWebpackPlugin
. This way, once the SourceMap is uploaded to the server, it will be immediately deleted from the local file system, ensuring that it does not remain 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 you enable "hidden-source-map"
, you should also set matchSourcemapsByFilename: true
in the GuanceSourceMapUploadWebpackPlugin
plugin. This configuration 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.
const { GuanceSourceMapUploadWebpackPlugin } = 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 build 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 GuanceSourceMapUploadWebpackPlugin({
...
deleteAfterUpload: true,
matchSourcemapsByFilename: true,
}),
]
: [],
],
}
How to DEBUG¶
If SourceMaps are not found during the run, you can set the environment variable DEBUG=guance:sourcemap-upload
or configure logLevel: verbose
when running the build command to view detailed runtime logs.
Precautions¶
Node Version > 10.13
¶
Considerations for 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 isdist/
, so the uploaded sourcemap file path to the Guance server would bedist/js/**.js.map
-
In this case, the uploaded file directory path would not match the error path, so you should add the configuration
root:'/'
orroot: ''
to ensure the upload path isjs/**.js.map
.