Source Map

Source Map is an information file that stores the mapping between the source code and the corresponding position of the compiled code, which is convenient for developers to locate the above code errors. In effect, it is a JSON key-value pair that stores location information using VLQ encoding and specific rules. In short, it can be understood that Source Map builds a bridge between the code before processing and the code after processing.

For front-end applications, the occurrence of JS errors directly affects the quality of front-end applications, so it is particularly important to locate and diagnose JS errors. The keynote listening cloud provides the source map to restore the real error location of the code and restore the JS error scene. This allows the developer to quickly locate the source code location of the error and the corresponding code block.

Source Map uploads are supported in two ways: CLI and Webpack plugin.

CLI instructions for use

Tingyun CLI is a CLI program, which is the main way to upload Source Map.

Installation

NPM installation

Current working directory installation：

Enter the front-end engineering directory and install the CLI package.
```
npm install @tingyun-common/cli
```
Verify that the installation is successful.
```
./node_modules/.bin/tingyun-cli -v
```

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

Install globally:

Installation.
```
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 problems in Linux and Mac environments, it is recommended to use root installation.
```
sudo npm install -g @tingyun-common/cli --unsafe-perm
```
Verify that the installation is successful.
```
tingyun-cli -v
```

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

Other NPM installations

Configure CLI download address:

--tingyuncli_cdnurl=<download address root path>

Examples of use:

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

Manually download the executable

You can Keynote listening cloud file download server view the released version of tingyun-cli and download the executable file for Linux, Mac, and Windows platforms. After downloading, you can rename to tingyun-cli.exe or tingyun-cli to use. Note that the executable is a CLI program and needs to be used in the terminal.

Use

1.Initialize.

Tingyun CLI depends on a configuration file to use. The configuration file name is .tingyunclirc or .tingyunclirc.toml and the format toml is. The profile information may be copied in the application settings or initialized by running tingyun -cli init the provided interactive information input tool. A configuration file needs to be guaranteed current directory or user directory present before Source Map can be uploaded using the CLI.

Execute the initialization command in the project working directory to generate the configuration file .tingyunclirc.toml.
```
tingyun-cli init -y
```

Open the configuration file. Configuration file usage toml format, generated configuration file description:

[auth]
# Platform access token, application settings acquisition
token = ""

[base]
# Application name, optional, tag function, application setting acquisition
app_name = ""
# Apply token, apply settings to get
app_token = ""
# sourcemap upload address, application settings acquisition
beacon = ""
# Product type, application setting acquisition
product_type = "web"

Copy the configuration information on the Application Settings>SourceMap page, paste it into a .tingyunclirc.toml file, and then save it.

Upload the Source Map.

Command structure:
```
tingyun-cli release upload <version> <upload file or directory> --sourcemap
```
In order to accurately parse errors reported by JS files of different versions, the Source Map file must be uploaded to a version file (see the complete command list below for version CLI commands). This version is the application version of the user project . Every time the JS file is repackaged, it needs to be uploaded with a new version.

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

In order to accurately associate the JS error version, the user project needs to set the variable TINGYUN_RELEASE globally on the page. The variable type is object, and the attribute ID identifies the version name. This value needs to be consistent with the version specified in the previous step at each release.
```
window.TINGYUN_RELEASE = {
    id: 'V1.0.0'
}
```
The probe will get the ID of the TINGYUN _ RELEASE and upload it as the application version.

CLI commands

View Version:

tingyun-cli -v

Interactive questionnaire mode initializes the configuration file in the current directory:

tingyun-cli init

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

tingyun-cli init -y

Show current version list

tingyun-cli release list

Delete the version

tingyun-cli release delete <release>

Create a version

tingyun-cli release new <release>

Upload the version

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

Flags Description:

--sourcemap: Process the uploaded file in the form of Source Map, recognize the.map file by default, and try to parse the sourcemapping mapping in.js.

--no-over write: The upload does not overwrite the file with the same name. It overwrites by default.

--config: Specifies the configuration file path, global flags, and takes effect for all command subcommands.

Example:

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

Web pack Plug-in Instructions

The Webpack plugin simplifies the CLI upload Source Map process for better integration into project releases.

Use

Installation.

Enter the root directory of the front-end project and install it through NPM:
```
npm install @tingyun-common/source-map-webpack-plugin --save-dev
```

Add the SourceMap plug-in to the Webpack configuration.

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

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

  //...
  plugins: [
    new TingyunSourceMapWebpackPlugin({
      //Specify the file directory generated by packaging, fill in according to the actual situation, for example: './dist'
      include: '<upload directory or file>',
      //Set the version number of the uploaded sourcemap. If not set, the plug-in will automatically generate it, for example; V1.0.0
      release: '<version number>'
      //Specify the uploaded configuration information. If the tingyun-cli configuration file .tingyunclirc or .tingyunclirc.toml exists in the current project directory, it does not need to be written.
      beacon: '<upload address>',
      appToken: '<app_token>',
      token: '<access_token>',
      productType: '<product type>', //web or mp
    }),
    // ...
    // Other plugins
  ],
};

The Webpack plug-in creates a version and uploads the Source Map every time it is executed. It is recommended to execute the plug-in only when it is packaged in the production environment to prevent a large number of unnecessary version uploads! Refer to the official Web pack documentation: Best Practices for Production Packaging.
- If the tingyun-cli configuration .tingyunclirc file or .tingyunclirc.toml exists in the current directory, the upload information may not be set in the Webpack plug-in configuration.

Demo Project

Project address

Configuration example

Here are some examples of how popular scaffolding projects can be used. The fundamental purpose is to add the Base Tone Listening Cloud Source Map plug-in in the Webpack configuration. If the following reference configuration does not cover your usage scenario, please configure it according to the actual situation.

Make sure the Webpack plugin is installed before using:

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

Then refer to the following configuration actions.

create-react-app

Recommended react-app-rewired to add Webpack plugin. If your project has used eject scripts to expose the Webpack configuration, please analyze the project configuration and add the Webpack plug-in.

Version used for example:

create-react-app 4.0.3

Installation react-app-rewired.

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

Modify package.json the script section of the script to use react-app-rewired the replacement 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 in 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 the webpack plug-in to the production environment
            config.plugins.push(
                new TingyunSourceMapWebpackPlugin({
                    include: "./build",
                    //Other configuration
                })
            )
        }
        return config;
    },
  }

Pack.
```
npm run build
```

After executing the packaging command, the console prints the upload information output by the plug-in.

vue-cli

Version used for example:

@vue/cli 4.5.13

Create or modify vue.config.js a file.

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

module.exports = {
  configureWebpack: (config) => {
    if (process.env.NODE_ENV === "production") {
      // Add the webpack plug-in to the production environment
      config.plugins.push(
          new TingyunSourceMapWebpackPlugin({
            include: "./dist",
            //Other configuration
          })
      )
    }
  },
};

Pack.

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 prints the upload information output by the plug-in.

angular-cli

Version used for example:

Angular CLI: 12.0.4

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

Modification angular.json.

"projects": {
  ...
  // [project] is the actual project name
  "[project]": {
    ...
    "architect": {
      ...
      // Modify the corresponding ng command, here we take modifying build as an example
      "build": {
        //Modify the 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 customization
              "path": "./webpack.config.js"
          }
        },
        "configurations": {
          "production": {
            // If sourcemap generation is not enabled, set sourcemap to be enabled.
            "sourceMap": true
          }
        }

Modify/create a Webpack configuration file.

The generation location of the configuration file here depends on the path configured in the 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;
};

Pack.

npm run build

After executing the packaging command, the console prints the upload information output by the plug-in.

Source Map

CLI instructions for use​

Installation​

NPM installation​

Other NPM installations​

Manually download the executable​

Use​

CLI commands​

Web pack Plug-in Instructions​

Use​

Demo Project​

Configuration example​

create-react-app​

vue-cli​

angular-cli​

CLI instructions for use

Installation

NPM installation

Other NPM installations

Manually download the executable

Use

CLI commands

Web pack Plug-in Instructions

Use

Demo Project

Configuration example

create-react-app

vue-cli

angular-cli