Source Maps

Source maps allow you to maintain debugging capabilities when using obfuscated code in production. They provide a way to map the obfuscated code back to your original source code, making it possible to trace errors and debug issues even after obfuscation.

How Source Maps Work with Shield

When you enable source maps in ByteHide Shield, the obfuscator generates a mapping file that browsers and debugging tools can use to show you the original code instead of the obfuscated version. This is particularly useful during development and when monitoring production errors.

Enabling Source Maps

To enable source maps with ByteHide Shield, use the sourceMap option in your configuration:

{
  "sourceMap": true,
  "sourceMapMode": "separate"
  // Other Shield options...
}

Source Map Options

ByteHide Shield provides several options to control how source maps are generated:

sourceMap

Type: boolean Default: false

Enables source map generation for obfuscated code.

sourceMapMode

Type: string Default: separate

Specifies source map generation mode:

• inline - adds source map at the end of each .js file
• separate - generates corresponding '.map' file with source map

sourceMapBaseUrl

Type: string Default: ''

Sets base URL to the source map import URL when using sourceMapMode: 'separate'.

Example:

{
  "sourceMap": true,
  "sourceMapMode": "separate",
  "sourceMapBaseUrl": "http://localhost:9000"
}

This results in:

//# sourceMappingURL=http://localhost:9000/your-file.js.map

sourceMapFileName

Type: string Default: ''

Sets file name for output source map when sourceMapMode: 'separate'.

Example:

{
  "sourceMap": true,
  "sourceMapMode": "separate",
  "sourceMapBaseUrl": "http://localhost:9000",
  "sourceMapFileName": "example"
}

This results in:

//# sourceMappingURL=http://localhost:9000/example.js.map

sourceMapSourcesMode

Type: string Default: sources-content

Controls sources and sourcesContent fields of the source map:

• sources-content - adds dummy sources field, adds sourcesContent field with the original source code
• sources - adds sources field with a valid source description, does not add sourcesContent field

When to Use Source Maps

Development Environment

In development, it's recommended to always enable source maps. This allows you to debug your code normally, despite the obfuscation being applied.

Example configuration for development:

{
  "sourceMap": true,
  "sourceMapMode": "inline",
  // Obfuscation settings can be less aggressive for development
}

Production Environment

For production, there are two approaches:

1. No source maps: Highest security, but difficult to debug

   {
     "sourceMap": false
     // Other obfuscation settings
   }
   

2. Protected source maps: Generate maps but store them securely

   {
     "sourceMap": true,
     "sourceMapMode": "separate",
     // Other obfuscation settings
   }
   

When using the second approach, make sure to:

• Store the source maps in a secure location
• Configure proper access control so only your team can access them
• Set up error tracking tools to use these source maps automatically

Security Considerations

While source maps are invaluable for debugging, they also expose your original source code. Consider these security practices:

1. Never serve source maps publicly on production websites
2. If you need production debugging, set up a secure system to access source maps only when needed
3. Configure your web server to restrict access to .map files
4. For serious security concerns, consider a hybrid approach where minimal source maps are generated that help with debugging but don't expose all original code

Using Source Maps with Error Tracking Tools

Most error tracking services (like Sentry, Rollbar, or LogRocket) can use source maps to provide readable stack traces. This gives you the best of both worlds: obfuscated code in production with readable error reports.

Typically, you'll need to:

1. Upload your source maps to the service
2. Ensure the correct source map URL is specified in your obfuscated files
3. Configure the service to use these source maps

Integration with Build Tools

Shield's source map options integrate well with popular build tools:

Webpack

// webpack.config.js
module.exports = {
  // ...other webpack config
  devtool: 'source-map', // Generate source maps with webpack
  plugins: [
    new ByteHideShieldPlugin({
      sourceMap: true,
      sourceMapMode: 'separate',
      // other Shield options
    })
  ]
};

Rollup

// rollup.config.js
export default {
  // ...other rollup config
  plugins: [
    bytehideShield({
      sourceMap: true,
      sourceMapMode: 'separate',
      // other Shield options
    })
  ],
  sourcemap: true // Tell rollup to generate source maps
};

By properly configuring source maps, you can maintain the security benefits of code obfuscation while preserving your ability to debug and monitor your application effectively.