How does Rspack's Source Map work?

Rspack's Source Map functionality is crucial for debugging and error tracking, allowing compiled code to be mapped back to the original source code. Here's a detailed explanation of Rspack's Source Map:

Basic Concepts of Source Map

Source Map is an information file that stores the mapping relationship between source code and compiled code. It allows developers to debug original source code in the browser instead of compiled code.

Source Map Types

Rspack supports multiple Source Map types, each with different trade-offs between performance and precision:

1. eval

The fastest Source Map type with the least information:

javascript
module.exports = {
  mode: 'development',
  devtool: 'eval'
}

Characteristics:

• Fastest build speed
• Each module is executed using eval()
• Does not include column information
• Not suitable for production

2. eval-source-map

Generates independent Source Map for each module:

javascript
module.exports = {
  mode: 'development',
  devtool: 'eval-source-map'
}

Characteristics:

• Relatively fast build speed
• Contains complete Source Map
• Suitable for development environment
• Larger file size

3. cheap-eval-source-map

Source Map without column information:

javascript
module.exports = {
  mode: 'development',
  devtool: 'cheap-eval-source-map'
}

Characteristics:

• Fast build speed
• Does not include column information
• Suitable for development environment
• Balance between performance and precision

4. cheap-module-eval-source-map

Source Map including Loader transformations:

javascript
module.exports = {
  mode: 'development',
  devtool: 'cheap-module-eval-source-map'
}

Characteristics:

• Includes Loader Source Map
• Does not include column information
• Suitable for development environment
• More accurate debugging information

5. source-map

Generates complete Source Map file:

javascript
module.exports = {
  mode: 'production',
  devtool: 'source-map'
}

Characteristics:

• Generates independent .map file
• Contains complete debugging information
• Slower build speed
• Suitable for production environment

6. hidden-source-map

Generates Source Map but does not reference it:

javascript
module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map'
}

Characteristics:

• Generates independent Source Map
• Not referenced in bundle
• Used for error tracking services
• Does not affect user experience

7. nosources-source-map

Only shows error line numbers, not source code:

javascript
module.exports = {
  mode: 'production',
  devtool: 'nosources-source-map'
}

Characteristics:

• Protects source code
• Only shows error location
• Suitable for production environment
• High security

Environment Configuration

Development Environment

javascript
module.exports = {
  mode: 'development',
  devtool: 'eval-cheap-module-source-map',
  devServer: {
    client: {
      overlay: {
        errors: true,
        warnings: false
      }
    }
  }
}

Recommended Configuration:

• eval-cheap-module-source-map: Balance performance and precision
• eval-source-map: When complete debugging information is needed
• cheap-module-eval-source-map: For large projects

Production Environment

javascript
module.exports = {
  mode: 'production',
  devtool: 'source-map',
  optimization: {
    minimize: true
  }
}

Recommended Configuration:

• source-map: Complete debugging information
• hidden-source-map: Error tracking services
• nosources-source-map: Protect source code

Source Map Optimization

1. Exclude Third-party Libraries

javascript
module.exports = {
  devtool: 'source-map',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            sourceMaps: true
          }
        }
      }
    ]
  }
}

2. Use Source Map DevTool

javascript
const { SourceMapDevToolPlugin } = require('@rspack/core');

module.exports = {
  plugins: [
    new SourceMapDevToolPlugin({
      filename: '[file].map',
      exclude: [/node_modules/],
      append: '\n//# sourceMappingURL=[url]'
    })
  ]
}

3. Configure Source Map Options

javascript
module.exports = {
  devtool: 'source-map',
  output: {
    devtoolModuleFilenameTemplate: 'webpack://[resource-path]?[loaders]',
    devtoolFallbackModuleFilenameTemplate: 'webpack:///[resource-path]?[hash]'
  }
}

Source Map and Error Tracking

1. Error Tracking Service

javascript
module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map',
  plugins: [
    new SentryWebpackPlugin({
      authToken: process.env.SENTRY_AUTH_TOKEN,
      org: 'your-org',
      project: 'your-project',
      include: './dist'
    })
  ]
}

2. Local Error Analysis

javascript
const sourceMap = require('source-map');

async function analyzeError(stackTrace) {
  const consumer = await new sourceMap.SourceMapConsumer(sourceMapData);
  const originalPosition = consumer.originalPositionFor({
    line: lineNumber,
    column: columnNumber
  });
  return originalPosition;
}

Performance Considerations

1. Build Time

Build time comparison for different Source Map types:

• eval: Fastest
• eval-source-map: Relatively fast
• cheap-eval-source-map: Fast
• source-map: Slower

2. File Size

Source Map increases file size:

• Development environment: Acceptable
• Production environment: Consider using CDN or separate storage

3. Memory Usage

Source Map uses additional memory:

• Large projects: Consider using cheap options
• Monitor memory usage

Best Practices

1. Development Environment:

   • Use eval-cheap-module-source-map
   • Enable error overlay
   • Fast feedback

2. Production Environment:

   • Use source-map or hidden-source-map
   • Configure error tracking services
   • Protect source code

3. Performance Optimization:

   • Exclude Source Map for third-party libraries
   • Use cheap options to improve performance
   • Reasonably choose Source Map type

4. Security Considerations:

   • Use nosources-source-map in production
   • Avoid exposing source code
   • Configure access control

5. Debugging Experience:

   • Configure browser Source Map
   • Use debugging tools
   • Provide clear error messages

Rspack's Source Map functionality provides developers with powerful debugging capabilities. Through reasonable configuration and usage, it can provide a good debugging experience while maintaining performance.