Upload SourceMap During Project Build¶
TrueWatch currently provides a webpack
plugin that allows you to easily upload SourceMap files for the corresponding directory during the build process of a Web project, eliminating the cumbersome manual upload process.
Note: Currently, only Web applications are supported.
Preparations¶
- Obtain the
OpenApi
domain address for the corresponding site; - Obtain the required
API KEY
forOpenApi
from TrueWatch here; - Obtain the
applicationId
,env
, andversion
information for the Web application on the TrueWatch platform. If there is no application, you need to create a new application; - Preparations are complete.
Webpack¶
Install @cloudcare/webpack-plugin
Modify the plugins
option in the webpack.config.js
file
// ....
const { SourceMapUploadWebpackPlugin } = require("@cloudcare/webpack-plugin")
module.exports = ({ mode }) => ({
//.....
devtool: "hidden-source-map",
plugins: [
//.....
new SourceMapUploadWebpackPlugin({
applicationId: "xxxxx", // TrueWatch application appid
apiKey: "xxxxxxxx", // open apikey
server: "https://console.xxx-xxx.cn",
filepaths: ["dist/"], // Directory to search, can be a file or directory
logLevel: "verbose", // Log level, optional
root: "dist/", // Directory to calculate relative paths, optional
env: "production", // TrueWatch application env, optional
version: "1.0.0", // TrueWatch application version, optional
}),
],
})
SourceMap WebpackPlugin Configuration Explanation¶
interface Options {
/**
*
* Files/directories to search for sourcemaps.
* All files matching the "extensions" list but not matching the "ignore" list will be searched
* for sourcemap JSON or `//#sourceMappingURL=` comments to find the generated file + sourcemap pair, then the sourcemap will be uploaded.
*/
filepaths: Array<string> | string
/**
* OpenApi Key generated by the TrueWatch platform, refer to (https://docs.truewatch.com/management/api-key/open-api/#_1) for generation method
*/
apiKey: string
/**
* OpenApi service of the TrueWatch platform
*/
server: string
/**
* applicationId of the TrueWatch RUM application (required)
*/
applicationId: string
/**
* version of the TrueWatch RUM application (optional)
*/
version?: string
/**
* env of the TrueWatch RUM application (optional)
*/
env?: string
/**
* Find all matching files but do not upload them, can be used for debugging
*/
dryRun?: boolean
/**
* Delete all found sourcemap files after upload.
*/
deleteAfterUpload?: boolean
/**
* If sourcemaps cannot be matched with their sourceMappingURL, try to match them by filename on the local disk
*/
matchSourcemapsByFilename: ?boolean
/**
* List of file extensions to search in the directory
* Default [".js", ".map"].
*/
extensions?: Array<string>
/**
* List of files to ignore
*/
ignore?: Array<string>
/**
* Directory to calculate relative paths. The relative path of the sourcemaps should be included in the path that generates the error, so
* the purpose of this parameter is to control the relative directory of the upload
* Default relative path from the execution directory to the search directory path.relative(process.cwd(), filepath)
*/
root?: string
/**
* Log level for debugging
*/
logLevel?: "quiet" | "normal" | "verbose"
/**
* Whether to ignore errors on failure, this configuration ensures that errors do not interrupt the build process. Default false, meaning errors will be thrown normally
*/
warnOnFailure?: boolean
}
SourceMap Visibility in Production Environment¶
In production environments, SourceMap files are usually not retained for security reasons. These files allow developers to map minified or compiled code back to the original source code, but if made public, they could expose the internal logic of the application, increasing security risks.
To safely handle SourceMaps, you can enable the deleteAfterUpload: true
option when configuring the SourceMapUploadWebpackPlugin. This ensures that once SourceMaps are uploaded to the server, they are immediately deleted from the local file system, preventing them from being left 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 "hidden-source-map"
is enabled, you should also set matchSourcemapsByFilename: true
in the SourceMapUploadWebpackPlugin. This configuration ensures that the plugin can identify and upload the corresponding SourceMap files based on the JavaScript file names, even if there are no explicit references in the generated code.
Through these measures, you can maintain the convenience of application debugging while effectively protecting the security of the source code.
const { SourceMapUploadWebpackPlugin } = 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 buidl 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 SourceMapUploadWebpackPlugin({
...
deleteAfterUpload: true,
matchSourcemapsByFilename: true,
}),
]
: [],
],
}
How to DEBUG¶
If the corresponding SourceMap is not found during the process, you can set the environment variable DEBUG=sourcemap-upload
or configure logLevel: verbose
to run the build command and view the detailed logs.
Notes¶
Node version > 10.13
¶
filepaths
and root
Configuration Notes:¶
-
In the Guance console, there is an error with the 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 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 isdist/
, and the sourcemap file path uploaded to the Guance server will bedist/js/**.js.map
-
In this case, the uploaded file directory path will not match the error path, so you should add the configuration
root:'/'
orroot: ''
to ensure the uploaded directory path isjs/**.js.map
.