Configuration Files

ByteHide Shield for JavaScript can be configured through JSON configuration files or through direct options in your build tools. This page explains how to create and use configuration files to customize protection settings.

Basic Configuration Structure

A Shield configuration file is a JSON file with the following structure:

{
  "compact": true,
  "controlFlowFlattening": false,
  "deadCodeInjection": false,
  "stringArray": true,
  "stringArrayEncoding": ["base64"],
  "selfDefending": false,
  "identifierNamesGenerator": "hexadecimal"
}

Configuration File Locations

Shield will look for configuration files in the following locations (in order of precedence):

1. Path specified in CLI or plugin options
2. .shieldrc.js or .shieldrc.json in your project root directory
3. shield field in your package.json

Using Configuration Files

With CLI

shield --config ./shield.config.json input.js -o output.js

With Webpack

// webpack.config.js
const ByteHideShieldPlugin = require('@bytehide/webpack-shield');

module.exports = {
  // ... other webpack config
  plugins: [
    new ByteHideShieldPlugin({
      configPath: './shield.config.json'
    })
  ]
}

With Next.js

// next.config.js
const withShield = require('@bytehide/next-shield')({
  configPath: './shield.config.json'
});

module.exports = withShield({
  // your next.js config
});

Configuration Options Reference

Below is a reference of all available configuration options:

Core Options

Code Transformation Options

String Protection Options

Identifier Protection Options

Debug Protection Options

Exclusion Options

Source Map Options

Preset Configurations

Shield comes with predefined configuration presets that can be used as a starting point:

{
  "optionsPreset": "Maximum"
}

Available presets:

• default: Basic protection with good performance
• Optimized: Minimal impact on performance
• Balance: Balanced protection and performance
• Maximum: Maximum protection with performance impact

You can also extend presets with your own options:

{
  "optionsPreset": "balance",
  "stringArrayEncoding": ["rc4"],
  "domainLock": ["example.com", ".my-website.org"]
}

Environment-Specific Configurations

You can create environment-specific configurations using different files:

• shield.config.json - Default configuration
• shield.dev.json - Development configuration
• shield.prod.json - Production configuration

Then specify which to use in your build tool:

// webpack.config.js
const ByteHideShieldPlugin = require('@bytehide/webpack-shield');
const env = process.env.NODE_ENV || 'development';

module.exports = {
  // ... other webpack config
  plugins: [
    new ByteHideShieldPlugin({
      configPath: `./shield.${env === 'production' ? 'prod' : 'dev'}.json`
    })
  ]
}

Example: Complete Configuration File

Here's an example of a comprehensive Shield configuration file for a production environment:

{
  "compact": true,
  "controlFlowFlattening": true,
  "controlFlowFlatteningThreshold": 0.7,
  "deadCodeInjection": true,
  "deadCodeInjectionThreshold": 0.4,
  "debugProtection": true,
  "disableConsoleOutput": true,
  "identifierNamesGenerator": "hexadecimal",
  "renameProperties": false,
  "selfDefending": true,
  "stringArray": true,
  "stringArrayEncoding": ["base64"],
  "stringArrayThreshold": 0.8,
  "transformObjectKeys": true,
  "unicodeEscapeSequence": false,
  "exclude": [
    "node_modules/**/*.js",
    "public/vendor/**/*.js"
  ],
  "reservedNames": [
    "^React$",
    "^Component$",
    "^useState$"
  ],
  "domainLock": [
    "example.com",
    ".example.org"
  ],
  "sourceMap": true,
  "sourceMapMode": "separate"
}

For more information about specific protection options, refer to their individual documentation pages.

Additional Configuration Options

Seed Configuration

ByteHide Shield allows you to set a specific seed for its random generator, which is useful for creating repeatable obfuscation results:

{
  "seed": 12345  // Any number or string to use as a seed
}

The seed option (default: 0) sets a seed value for the random generator used during the obfuscation process. When you set a specific seed:

• Obfuscated output becomes deterministic
• Multiple runs with the same seed produce identical results
• Different seeds produce different obfuscation patterns

This is particularly valuable in CI/CD environments or when you need to reproduce specific obfuscation results for testing or debugging purposes.

If the seed is set to 0 (default), the random generator will work without a fixed seed, producing different results each time.

Import Handling

To prevent obfuscation of require/import statements in your code:

{
  "ignoreImports": true  // Default is false
}

The ignoreImports option (default: false) prevents obfuscation of require imports. This is valuable when your runtime environment requires these imports to use static strings only.

For example, with this option enabled, code like:

const express = require('express');
const moment = require('moment');

Will remain unchanged, even when other string literals are obfuscated.

This option is particularly helpful when:

• Working with module systems that need string literals for dynamic imports
• Using systems that rely on static analysis of imports
• Working with bundlers or tools that inspect imports directly

Target Environment

ByteHide Shield can optimize the obfuscation for different environments:

{
  "target": "browser"  // Default value
  // Other options: "browser-no-eval", "node"
}

The target option allows you to specify the execution environment for your obfuscated code. Available values:

• browser (default): Optimized for browser environments
• browser-no-eval: Browser optimization without using eval (for environments with Content Security Policies)
• node: Optimized for Node.js environments

While the output code for browser and node targets is usually identical, some browser-specific protection options are not compatible with the node target.

The browser-no-eval target is particularly useful when your application must run in environments with strict Content Security Policies (CSP) that forbid the use of eval and similar functions.

Target-Specific Considerations:

Browser Target:

• Compatible with all ByteHide Shield protections
• May use eval for certain protections
• Optimized for browser JavaScript engines

Browser-No-Eval Target:

• Compatible with most protections but avoids eval
• Suitable for apps with strict CSP
• Slightly different protection implementation for certain features

Node Target:

• Disables browser-specific protections like domainLock
• Optimized for server-side execution
• Avoids browser-specific code patterns

Choose the target that best matches your deployment environment to ensure maximum compatibility and protection.