Source Map

Source Map is an information file that stores the mapping of positions between source code and compiled code, making it easier for developers to locate the above code errors. In fact, it is a JSON key-value pair that uses VLQ encoding and specific rules to store position information. In simple terms, Source Map can be understood as building a bridge between the code before processing and the code after processing.

For frontend applications, the occurrence of JS errors directly affects the quality of the frontend application, so the location and diagnosis of JS errors are particularly important. Tingyun provides Source Map upload to restore the true error location of the code, restoring the JS error scene. This allows developers to quickly locate the source code position of the error and the corresponding code block.

Source Map upload supports two methods: CLI and Webpack plugin.

CLI Usage Instructions

Tingyun CLI is a CLI program and is the main way to upload Source Maps.

Installation

npm Installation

Current Working Directory Installation:

Enter the frontend project directory and install the CLI package.
```
npm install @tingyun-common/cli
```
Verify successful installation.
```
./node_modules/.bin/tingyun-cli -v
```

If the tingyun-cli version is printed in the terminal, the installation is successful.

Global Installation:

Install.
```
npm install -g @tingyun-common/cli --unsafe-perm
```
You need to ensure that you have permission to access the global node_modules directory. If you encounter permission issues in Linux or Mac environments, it is recommended to install as root.
```
sudo npm install -g @tingyun-common/cli --unsafe-perm
```
Verify successful installation.
```
tingyun-cli -v
```

If the tingyun-cli version is printed in the terminal, the installation is successful.

Other npm Installation

Configure CLI download address:

--tingyuncli_cdnurl=<download address root path>

Usage example:

npm install @tingyun-common/cli --tingyuncli_cdnurl=http://example.com/path

Manually Download Executable Files

You can check the released versions of tingyun-cli on the Tingyun File Download Server and download executable files for Linux, Mac, and Windows platforms. After downloading, you can rename it to tingyun-cli.exe or tingyun-cli for use. Note that the executable file is a CLI program and needs to be used in the terminal.

Usage

Initialize.

Tingyun CLI relies on a configuration file to use. The configuration file name is .tingyunclirc or .tingyunclirc.toml, in toml format. Configuration file information can be copied from application settings or initialized through the interactive information input tool provided by running tingyun-cli init. Before using CLI to upload Source Map, you need to ensure that a configuration file exists in the current directory or user directory.
- Execute the initialization command in the project working directory to generate the configuration file .tingyunclirc.toml.
```
tingyun-cli init -y
```
- Open the configuration file. The configuration file uses the toml format. The generated configuration file description:
```
[auth]
# Platform access token, obtained from application settings
token = ""

[base]
# Application name, optional, for marking purposes, obtained from application settings
app_name = ""
# Application token, obtained from application settings
app_token = ""
# sourcemap upload address, obtained from application settings
beacon = ""
# Product type, obtained from application settings 
product_type = "web"
```
- Copy the configuration information from the Application Settings > SourceMap page, paste it into the .tingyunclirc.toml file, and then save.
Upload Source Map.

Command structure:
```
tingyun-cli release upload <version> <upload file or directory> --sourcemap
```
In order to accurately parse errors in different versions of JS files, Source Map files must be uploaded to a certain version (see the complete command list below for version CLI commands). This version is the application version of the user's project, and each time the JS file is repackaged, the version needs to be changed for uploading.

Example:
```
tingyun-cli release upload V1.0.0 ./dist --sourcemap
```
Upload Source Map files from the dist directory to version V1.0.0.
Set application version.

In order to accurately associate JS error versions, the user's project needs to set the global variable TINGYUN_RELEASE in the page, which is an object with the property id identifying the version name. This value needs to be consistent with the version specified in the previous step each time a new version is released.
```
window.TINGYUN_RELEASE = {
    id: 'V1.0.0'
}
```
The agent will get the id of TINGYUN_RELEASE as the application version for uploading.

CLI Commands

View version:

tingyun-cli -v

Interactive questionnaire mode to initialize the configuration file in the current directory:

tingyun-cli init

--yes, -y can skip the questionnaire and generate a template configuration file:

tingyun-cli init -y

Display current version list

tingyun-cli release list

Delete version

tingyun-cli release delete <release>

Create version

tingyun-cli release new <release>

Upload version

tingyun-cli release upload <release> <files>... [flags]

flags description:

--sourcemap: Process upload files as Source Map, by default identify .map files, and try to parse .js sourcemapping mapping.

--no-overwrite: Upload does not overwrite files with the same name, overwrite by default.

--config: Specify the configuration file path, global flags, effective for all commands and subcommands.

Example:

tingyun-cli release upload V1.0.0 ./dist --sourcemap --config /my/config/dir/.tingyunclirc

Webpack Plugin Usage Instructions

The Webpack plugin simplifies the CLI upload Source Map process and can better integrate into the project's version release.

Usage

Install.

Enter the root directory of the frontend project and install via npm:
```
npm install @tingyun-common/source-map-webpack-plugin --save-dev
```

Add the SourceMap plugin to the Webpack configuration.

// Import sourcemap plugin
const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');

module.exports = {
  // Recommended to use only in production mode
  mode: 'production',

  //... 
  plugins: [
    new TingyunSourceMapWebpackPlugin({
      // Specify the directory of packaged generated files, fill in according to actual situation, e.g.: './dist'
      include: '<upload directory or file>',
      // Set the version number for uploading sourcemap, if not set, the plugin will automatically generate, e.g.; V1.0.0
      release: '<version number>'
      // Specify upload configuration information. If there is a tingyun-cli configuration file .tingyunclirc or .tingyunclirc.toml in the current project directory, this can be omitted
      beacon: '<upload address>',
      appToken: '<app_token>',
      token: '<access_token>',
      productType: '<product type>', //web or mp
    }),
    // ...
    // Other plugins
  ],
};

The Webpack plugin will create a version and upload Source Map each time it is executed. It is recommended to only execute the plugin when packaging for production environment to prevent a large number of unnecessary version uploads! Please refer to the Webpack official documentation: Best Practices for Production Packaging.
If there is a tingyun-cli configuration file .tingyunclirc or .tingyunclirc.toml in the current directory, the upload information can be omitted in the Webpack plugin configuration.

Demo Project

Project Address

Configuration Examples

Below are examples of usage methods for popular scaffold projects. The fundamental purpose is to add the Tingyun Source Map plugin to the Webpack configuration. If the reference configurations listed below do not cover your usage scenario, please configure according to your actual situation.

Before using, first make sure the Webpack plugin is installed:

npm install @tingyun-common/source-map-webpack-plugin --save-dev

Then refer to the following configurations.

create-react-app

It is recommended to use react-app-rewired to add the Webpack plugin. If you have already used the eject script to expose the Webpack configuration in your project, please analyze the project configuration yourself to add the Webpack plugin.

Version used in the example:

create-react-app 4.0.3

Install react-app-rewired.

npm install react-app-rewired --save-dev

Modify the script part of package.json, using react-app-rewired to replace react-scripts.

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-scripts eject"
},

Add or modify config-overrides.js at the project root directory.

const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');

module.exports = {
    webpack: (config) => {
        if (process.env.NODE_ENV === "production") {
            if (!config.plugins) {
                config.plugins = [];
            }
            // Add webpack plugin for production environment
            config.plugins.push(
                new TingyunSourceMapWebpackPlugin({
                    include: "./build",
                    // Other configurations
                })
            )
        }
        return config;
    },
  }

Package.
```
npm run build
```

After executing the packaging command, the console will print the upload information output by the plugin.

vue-cli

Version used in the example:

@vue/cli 4.5.13

Create or modify the vue.config.js file.

const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');

module.exports = {
  configureWebpack: (config) => {
    if (process.env.NODE_ENV === "production") {
      // Add webpack plugin for production environment
      config.plugins.push(
          new TingyunSourceMapWebpackPlugin({
            include: "./dist",
            // Other configurations
          })
      )
    }
  },
};

Package.

Please fill in the packaging command according to the actual situation. The default is build.
```
npm run build
```

After executing the packaging command, the console will print the upload information output by the plugin.

angular-cli

Version used in the example:

Angular CLI: 12.0.4

Enter the project directory and install @angular-builders/custom-webpack.
```
npm install @angular-builders/custom-webpack --save-dev
```

Modify angular.json.

"projects": {
  ...
  // [project] is the actual project name
  "[project]": {
    ...
    "architect": {
      ...
      // Modify the corresponding ng command, here taking modifying build as an example
      "build": {
        // Modify default builder
        // "builder": "@angular-devkit/build-angular:browser",
        "builder": "@angular-builders/custom-webpack:browser"
        "options": {
          // Add custom webpack file configuration
          "customWebpackConfig": {
              // webpack configuration file name, name is customizable
              "path": "./webpack.config.js"
          }
        },
        "configurations": {
          "production": {
            // If sourcemap generation is not enabled, set to enable sourcemap
            "sourceMap": true
          }
        }

Modify/create Webpack configuration file.

The generation location of the configuration file here depends on the path configured in angular.json.

webpack.config.js

const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');

module.exports = (config, options) => {
    if (config.mode === "production") {
        if (!config.plugins) {
            config.plugins = [];
        }
        config.plugins.push(
            new TingyunSourceMapWebpackPlugin({
              include: "./dist",
              // Upload configuration can be specified here or create a cli configuration file
            })
        )
    }

    return config;
};

Package.

npm run build

After executing the packaging command, the console will print the upload information output by the plugin.

CLI Usage Instructions​

Installation​

npm Installation​

Other npm Installation​

Manually Download Executable Files​

Usage​

CLI Commands​

Webpack Plugin Usage Instructions​

Usage​

Demo Project​

Configuration Examples​

create-react-app​

vue-cli​

angular-cli​

CLI Usage Instructions

Installation

npm Installation

Other npm Installation

Manually Download Executable Files

Usage

CLI Commands

Webpack Plugin Usage Instructions

Usage

Demo Project

Configuration Examples

create-react-app

vue-cli

angular-cli