Troubleshooting Guide for ByteHide Shield

While ByteHide Shield is designed to work smoothly with most JavaScript applications, you may occasionally encounter issues. This guide provides solutions to common problems and strategies for diagnosing and fixing them.

Common Issues and Solutions

Application Crashes After Obfuscation

If your application crashes after obfuscation, try these steps:

Enable source maps: Add the sourceMap: true option to your configuration to make debugging easier.
Check for global name conflicts: If you have renameGlobals: true, ensure that critical global identifiers are added to the reservedNames list:
```
{
  "renameGlobals": true,
  "reservedNames": ["^jQuery$", "^React$", "^APP_CONFIG$"]
}
```
Look for property renaming issues: If you've enabled renameProperties, try setting it to false to see if that resolves the issue. If it does, use reservedNames with property-specific patterns:
```
{
  "renameProperties": true,
  "reservedNames": ["^props$", "^_reactInternals"]
}
```
Disable strong obfuscation options one by one: Start with disabling controlFlowFlattening and selfDefending, then gradually reenable them to isolate the problematic option.

Module System Compatibility Issues

Modern JavaScript uses various module systems (ESM, CommonJS). If you experience module-related issues:

Check for import/require statements: Ensure that ignoreImports is set to true if you're having trouble with dynamic imports:
```
{
  "ignoreImports": true
}
```
Preserve critical module exports: Add essential export names to the reservedNames list:
```
{
  "reservedNames": ["^export", "^module.exports"]
}
```
Test with different target settings: Try switching between browser, browser-no-eval, and node target settings to match your environment.

Framework-Specific Issues

React Issues

Component rendering problems: Ensure React component names and lifecycle methods are preserved:

{
  "reservedNames": ["^render$", "^componentDidMount$", "^useState$", "^useEffect$"]
}

React hooks failing: Add React hook patterns to reserved names:
```
{
  "reservedNames": ["^use[A-Z]"]
}
```

Angular Issues

Decorator problems: Preserve Angular decorators:

{
  "reservedNames": ["^Component$", "^Injectable$", "^NgModule$"]
}

Injection issues: Ensure dependency injection patterns are preserved:

{
  "reservedStrings": ["injectable", "injector", "InjectionToken"]
}

Performance Issues

Slow application startup: Reduce the aggressiveness of control flow flattening:

{
  "controlFlowFlattening": true,
  "controlFlowFlatteningThreshold": 0.2  // Lower value means less transformation
}

High memory usage: Reduce dead code injection or disable it:

{
  "deadCodeInjection": true,
  "deadCodeInjectionThreshold": 0.1  // Lower value or set to false
}

Slow runtime performance: Adjust string array settings:

{
  "stringArray": true,
  "stringArrayThreshold": 0.5,  // Lower to obfuscate fewer strings
  "stringArrayEncoding": []     // Remove encoding for better performance
}

Integration Issues with Build Tools

Webpack Issues

Errors in webpack build: Ensure the correct plugin configuration:

// webpack.config.js
module.exports = {
  // ...
  plugins: [
    new ByteHideShieldPlugin({
      // ensure these options are compatible with your webpack version
      sourceMap: true,
      outputPath: path.resolve(__dirname, 'dist')
    })
  ]
};

Compatibility with other plugins: Make sure ByteHide Shield runs at the right stage in your webpack configuration.

Rollup Issues

Proper plugin ordering: Ensure ByteHide Shield is in the correct position in the plugins array:

// rollup.config.js
export default {
  // ...
  plugins: [
    // Process source files first
    resolve(),
    commonjs(),
    // Apply ByteHide Shield before final transformations
    bytehideShield({
      // options
    }),
    // Final transformations
    terser()
  ]
};

Diagnostic Techniques

Progressive Testing

If you're having trouble identifying which option is causing issues:

Start with minimal obfuscation: Begin with a bare-bones configuration:

{
  "compact": true,
  "stringArray": true,
  "stringArrayThreshold": 0.5
}

Add features incrementally: Add one feature at a time, testing your application after each addition.
Use binary search for options: If you have many options, try disabling half of them at a time to narrow down the problematic one faster.

Debug Mode

Enable extended logging to help identify issues:

{
  "log": true
}

This will provide more detailed information about the obfuscation process.

Source Map Debugging

When troubleshooting with source maps:

Enable inline source maps for development:

{
  "sourceMap": true,
  "sourceMapMode": "inline"
}

Use browser developer tools to step through the obfuscated code with the help of source maps.

Consider configuring an isolated debug build with both obfuscation and complete source maps for troubleshooting:

{
  "sourceMap": true,
  "controlFlowFlattening": true,
  "selfDefending": false  // Disable for easier debugging
}

Environment-Specific Issues

Node.js Compatibility

File system or module issues: Make sure to use the node target:
```
{
  "target": "node"
}
```
Command-line tools: For tools run from the command line, ensure global binaries are excluded from obfuscation.

Browser Compatibility

Older browser support: Some obfuscation techniques may be too advanced for older browsers. Test your application in target browsers after obfuscation.
Eval restrictions: If you're working in an environment with Content Security Policy (CSP) restrictions, use:
```
{
  "target": "browser-no-eval"
}
```

Getting Additional Help

If you've tried the solutions in this guide and are still experiencing issues:

Check your configuration for conflicting or incompatible options
Review your exclusion patterns to ensure critical code isn't being obfuscated incorrectly
Test with a smaller subset of your code to isolate the issue
Contact ByteHide support with detailed information about your setup and the issues you're encountering

Prevention Tips

To prevent issues in future projects:

Create a test suite specifically for post-obfuscation verification
Use a staging environment to test obfuscated code before production
Maintain separate configurations for development, testing, and production
Document application-specific exclusions for future reference
Keep your ByteHide Shield integration updated to the latest version