Rollup Integration

ByteHide Shield provides a dedicated Rollup plugin that allows you to seamlessly protect your JavaScript code during the build process. This guide explains how to install and configure the Shield Rollup plugin.

Installation

Install the ByteHide Shield Rollup plugin from npm:

npm install --save-dev @bytehide/rollup-shield

Or with yarn:

yarn add --dev @bytehide/rollup-shield

Basic Setup

Add the Shield plugin to your Rollup configuration:

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

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    bytehideShield({
      projectToken: 'your-project-token' // Required: Get this from your ByteHide account
    })
  ]
};

With this minimal configuration, Shield will apply default protections to your bundled code.

Configuration Options

The Rollup plugin accepts the following options:

Advanced Configuration

For more advanced use cases, you can provide additional Shield protection options:

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

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    bytehideShield({
      projectToken: 'your-project-token',
      distDir: 'build',
      replace: true,
      exclude: ['vendor.js', 'polyfills.js'],
      config: {
        controlFlowFlattening: true,
        stringArray: true,
        stringArrayEncoding: ['base64'],
        selfDefending: true,
        identifierNamesGenerator: 'hexadecimal',
        renameProperties: false,
        reservedNames: [
          '^React$', 
          '^useState$', 
          '^Component$'
        ]
      }
    })
  ]
};

Environment-Specific Configuration

You can apply different protection settings based on the environment:

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

const isProd = process.env.NODE_ENV === 'production';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    // Only apply Shield in production builds
    isProd && bytehideShield({
      projectToken: process.env.BYTEHIDE_PROJECT_TOKEN,
      config: {
        // More aggressive settings for production
        controlFlowFlattening: true,
        stringArray: true,
        stringArrayEncoding: ['base64'],
        selfDefending: true
      }
    })
  ].filter(Boolean) // Filter out falsy plugins
};

File Exclusions

You can exclude specific files from obfuscation using the exclude option:

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

export default {
  // ...rollup config
  plugins: [
    bytehideShield({
      projectToken: 'your-project-token',
      exclude: [
        'node_modules/**/*.js', // Exclude all node_modules
        'src/vendor/**/*.js',    // Exclude vendor files
        'src/polyfills.js'       // Exclude specific file
      ]
    })
  ]
};

Integration with Other Rollup Plugins

When using Shield with other Rollup plugins, pay attention to the order of plugins:

// rollup.config.js
import bytehideShield from '@bytehide/rollup-shield';
import { terser } from 'rollup-plugin-terser';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    // Resolve dependencies and convert to ES modules first
    resolve(),
    commonjs(),
    
    // Minify the code
    terser(),
    
    // Apply Shield protections last
    bytehideShield({
      projectToken: 'your-project-token'
    })
  ]
};

Using Source Maps

To generate source maps for your obfuscated code:

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

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    sourcemap: true // Enable source maps in Rollup output
  },
  plugins: [
    bytehideShield({
      projectToken: 'your-project-token',
      config: {
        sourceMap: true,             // Enable source maps in Shield
        sourceMapMode: 'separate'    // Generate separate .map files
      }
    })
  ]
};

Complete Example

Here's a complete example of a production Rollup configuration with Shield:

// rollup.config.js
import bytehideShield from '@bytehide/rollup-shield';
import { terser } from 'rollup-plugin-terser';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import babel from '@rollup/plugin-babel';

const isProd = process.env.NODE_ENV === 'production';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm',
    entryFileNames: '[name].[hash].js',
    chunkFileNames: 'chunks/[name].[hash].js',
    sourcemap: !isProd
  },
  plugins: [
    resolve(),
    commonjs(),
    babel({
      babelHelpers: 'bundled',
      presets: ['@babel/preset-env', '@babel/preset-react']
    }),
    isProd && terser(),
    isProd && bytehideShield({
      projectToken: process.env.BYTEHIDE_PROJECT_TOKEN,
      replace: true,
      exclude: ['vendor/**/*.js'],
      config: {
        controlFlowFlattening: true,
        controlFlowFlatteningThreshold: 0.7,
        stringArray: true,
        stringArrayEncoding: ['base64'],
        stringArrayThreshold: 0.8,
        deadCodeInjection: true,
        deadCodeInjectionThreshold: 0.4,
        selfDefending: true,
        identifierNamesGenerator: 'hexadecimal',
        reservedNames: [
          '^React$', '^useState$', '^useEffect$',
          '^render$', '^Component$'
        ]
      }
    })
  ].filter(Boolean)
};

Troubleshooting

Common Issues

Large Bundle Size

If your bundle size becomes too large after obfuscation:

• Reduce the threshold values for controlFlowFlattening and deadCodeInjection
• Disable deadCodeInjection which can increase size significantly
• Use more selective file exclusions

Performance Issues

If runtime performance suffers:

• Apply Shield only to production builds
• Use lighter protection settings for performance-critical parts
• Balance security and performance by adjusting threshold values

Next Steps

• Get your project token
• Learn about protection options
• Configure exclusions and reserved items