Exclusions and Reserved Items

In many cases, you may need to exclude certain portions of your code from obfuscation to ensure functionality. ByteHide Shield provides several ways to exclude code from being protected.

Code-Level Exclusions

You can exclude specific parts of your code from obfuscation using special comments. This is especially useful when you need to keep certain functions or sections of code unobfuscated while protecting the rest of your application.

Disabling Obfuscation for Individual Items

To exclude a single function, variable, or statement, add a //bytehide-shield:disable comment on the line before the item:

//bytehide-shield:disable
function activateLicense(licenseKey) {
  // This function will not be obfuscated
  localStorage.setItem("license", licenseKey);
}

//bytehide-shield:disable
const API_URL = "https://api.example.com/v1";

// This code WILL be obfuscated
function validateUser(userId) {
  return fetch(`${API_URL}/users/${userId}`);
}

Disabling Obfuscation for Code Blocks

To exclude multiple lines or blocks of code, use the block comment syntax with /* bytehide-shield:disable */ and /* bytehide-shield:enable */:

/* bytehide-shield:disable */
// Everything between these markers will not be obfuscated
const activateLicense = (license) => {
  localStorage.setItem("license", license);
};

const getLicense = async (user) => {
  return await fetch("https://api.example.com/auth", {
    method: "POST",
    body: JSON.stringify(user)
  });
};
/* bytehide-shield:enable */

// Code after the enable marker will be obfuscated normally
getLicense({ id: 1020, name: "ByteHide" });

This approach is particularly useful for:

• License verification code that needs to be human-readable
• Integration points with external systems
• Debugging sections in your production code
• Code sections with specific formatting requirements

File Exclusions

You can exclude entire files from being processed by Shield using the exclude option. This is particularly useful for third-party libraries, polyfills, or any code that should remain untouched.

Using Configuration Files

In your Shield configuration file:

{
  "exclude": ["vendor/**/*.js", "polyfills.js", "external/**/*.js"]
}

Using CLI

When using the Shield CLI:

shield --exclude 'vendor/**/*.js,polyfills.js,external/**/*.js' input.js -o output.js

In Build Tool Integrations

For webpack:

// webpack.config.js
module.exports = {
  // ...
  plugins: [
    new ByteHideShieldPlugin({
      exclude: ['vendor/**/*.js', 'polyfills.js']
    })
  ]
};

For rollup:

// rollup.config.js
import { bytehideShield } from '@bytehide/rollup-shield';

export default {
  // ...
  plugins: [
    bytehideShield({
      exclude: ['vendor/**/*.js', 'polyfills.js']
    })
  ]
};

Reserved Names

The reservedNames option allows you to specify identifiers that should not be renamed during obfuscation. This is useful for preserving function or variable names that might be referenced externally.

{
  "reservedNames": [
    "^someVariable",
    "functionParameter_\\d",
    "React",
    "^render$",
    "^Component$",
    "^useState$"
  ]
}

This will preserve:

• Any identifier starting with "someVariable"
• Identifiers matching pattern "functionParameter_" followed by digits
• The "React" identifier
• Any identifier exactly matching "render", "Component", or "useState"

Reserved Strings

The reservedStrings option prevents transformation of string literals that match specific patterns:

{
  "reservedStrings": [
    "react-native",
    "\\.\/src\/test",
    "some-string_\\d",
    "^license:"
  ]
}

This will preserve:

• String literals containing "react-native"
• Strings containing "./src/test"
• Strings matching pattern "some-string_" followed by digits
• Strings starting with "license:"

Global Identifiers

By default, Shield does not rename global variables and function names. To enable renaming of global identifiers, use the renameGlobals option. However, this might break your code if external resources reference these globals.

{
  "renameGlobals": true
}

Combining Exclusion Methods

You can combine multiple exclusion methods to create a comprehensive exclusion strategy:

{
  "exclude": ["vendor/**/*.js", "polyfills.js"],
  "reservedNames": ["^React$", "^Component$", "^useState$"],
  "reservedStrings": ["API_KEY", "LICENSE_"],
  "renameGlobals": false
}

And use code-level exclusions for specific sections:

// Configuration and imports will be obfuscated
import React from 'react';
const config = { timeout: 5000 };

/* bytehide-shield:disable */
// License validation code remains readable
function validateLicense(key) {
  const hash = btoa(key.split('').reverse().join(''));
  return hash === 'TcVkIjNpYXJ8PDw=';
}
/* bytehide-shield:enable */

// The rest of the application is protected
function App() {
  // Application code...
}

Best Practices for Exclusions

1. Exclude third-party libraries: Don't obfuscate code from npm packages or CDNs
2. Reserve API function names: Any function exposed to external code should be reserved
3. Reserve event handler names: Functions used as event handlers often need their original names
4. Exclude polyfills: Browser compatibility code should remain untouched
5. Reserve configuration strings: API keys, endpoints, and configuration strings are often better left readable
6. Use code-level exclusions sparingly: Only disable obfuscation for code that absolutely needs to remain readable

Example: React Application

For a typical React application, you might use:

{
  "exclude": ["node_modules/**/*.js"],
  "reservedNames": [
    "^React$", "^Component$", "^useState$", "^useEffect$",
    "^render$", "^componentDidMount$",
    "^mapStateToProps$", "^mapDispatchToProps$",
    "^connect$"
  ],
  "reservedStrings": [
    "^http(s)?://", "^data:image"
  ]
}

And in your code:

import React, { useState } from 'react';

// Regular component code (will be obfuscated)
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  
  /* bytehide-shield:disable */
  // Keep authentication logic readable for maintenance
  const authenticateUser = async (credentials) => {
    const response = await fetch('https://api.example.com/auth', {
      method: 'POST',
      body: JSON.stringify(credentials)
    });
    return response.json();
  };
  /* bytehide-shield:enable */
  
  // Rest of component (will be obfuscated)
  return (
    <div className="user-profile">
      {/* Component JSX */}
    </div>
  );
}

This ensures React API functions remain unobfuscated while protecting your application logic, with specific sections kept readable for maintenance.