Configuration flags

Customize Scramjet’s behavior with feature flags and site-specific overrides

Scramjet provides a comprehensive set of feature flags that allow you to customize its behavior. These flags can be set globally or overridden on a per-site basis.

Global feature flags

Feature flags are configured when creating a ScramjetController instance:

const { ScramjetController } = $scramjetLoadController();

const scramjet = new ScramjetController({
  prefix: '/scramjet/',
  flags: {
    strictRewrites: true,
    captureErrors: true,
    sourcemaps: true,
    // ... other flags
  },
});

await scramjet.init();

Available flags

serviceworkers

Type: boolean Default: false

Enables service worker support within proxied pages.

const scramjet = new ScramjetController({
  flags: {
    serviceworkers: true,
  },
});

Enabling service workers in proxied contexts can be complex and may cause unexpected behavior. Only enable this if you need it.

syncxhr

Type: boolean Default: false

Enables synchronous XMLHttpRequest support.

const scramjet = new ScramjetController({
  flags: {
    syncxhr: true,
  },
});

Synchronous XHR is deprecated in modern browsers. Enable this only for legacy compatibility.

strictRewrites

Type: boolean Default: true

Enforces strict URL rewriting rules to ensure all URLs are properly proxified.

const scramjet = new ScramjetController({
  flags: {
    strictRewrites: true,
  },
});

Keep this enabled for maximum security and reliability. Disabling it may allow some URLs to bypass the proxy.

rewriterLogs

Type: boolean Default: false

Enables verbose logging from the URL rewriter for debugging purposes.

const scramjet = new ScramjetController({
  flags: {
    rewriterLogs: true,
  },
});

captureErrors

Type: boolean Default: true

Captures and handles JavaScript errors within proxied contexts.

const scramjet = new ScramjetController({
  flags: {
    captureErrors: true,
  },
});

cleanErrors

Type: boolean Default: false

Cleans error stack traces to remove proxy-related information.

const scramjet = new ScramjetController({
  flags: {
    cleanErrors: true,
  },
});

scramitize

Type: boolean Default: false

Enables additional obfuscation and protection mechanisms.

const scramjet = new ScramjetController({
  flags: {
    scramitize: true,
  },
});

sourcemaps

Type: boolean Default: true

Enables source map support for better debugging of rewritten JavaScript.

const scramjet = new ScramjetController({
  flags: {
    sourcemaps: true,
  },
});

destructureRewrites

Type: boolean Default: false

Uses destructuring patterns in rewritten code for potentially better performance.

const scramjet = new ScramjetController({
  flags: {
    destructureRewrites: true,
  },
});

interceptDownloads

Type: boolean Default: false

Intercepts file downloads and fires download events that you can handle.

const scramjet = new ScramjetController({
  flags: {
    interceptDownloads: true,
  },
});

await scramjet.init();

// Listen for downloads
scramjet.addEventListener('download', (event) => {
  console.log('Download intercepted:', event.download);
});

See Event handling for more details on download interception.

allowInvalidJs

Type: boolean Default: true

Allows execution of JavaScript that may not parse correctly.

const scramjet = new ScramjetController({
  flags: {
    allowInvalidJs: true,
  },
});

Some websites use non-standard JavaScript that may not parse correctly. This flag provides better compatibility at the cost of stricter error checking.

allowFailedIntercepts

Type: boolean Default: true

Allows requests to proceed even if interception fails.

const scramjet = new ScramjetController({
  flags: {
    allowFailedIntercepts: true,
  },
});

Site-specific flag overrides

You can override flags for specific domains using the siteFlags configuration:

const scramjet = new ScramjetController({
  prefix: '/scramjet/',
  flags: {
    strictRewrites: true,
    captureErrors: true,
    sourcemaps: true,
  },
  siteFlags: {
    // Override flags for example.com
    'example.com': {
      rewriterLogs: true,
      strictRewrites: false,
    },
    // Override flags for api.github.com
    'api.github.com': {
      syncxhr: true,
      captureErrors: false,
    },
  },
});

Site-specific flags are useful when certain websites require different settings for compatibility.

Common configuration presets

Here are some common flag configurations for different use cases:

Development

const scramjet = new ScramjetController({
  flags: {
    strictRewrites: true,
    rewriterLogs: true,
    captureErrors: true,
    cleanErrors: false,
    sourcemaps: true,
    allowInvalidJs: true,
    allowFailedIntercepts: true,
  },
});

Production

const scramjet = new ScramjetController({
  flags: {
    strictRewrites: true,
    rewriterLogs: false,
    captureErrors: true,
    cleanErrors: true,
    sourcemaps: false,
    scramitize: true,
    allowInvalidJs: true,
    allowFailedIntercepts: true,
  },
});

Maximum compatibility

const scramjet = new ScramjetController({
  flags: {
    strictRewrites: false,
    rewriterLogs: false,
    captureErrors: true,
    cleanErrors: true,
    sourcemaps: true,
    syncxhr: true,
    serviceworkers: true,
    allowInvalidJs: true,
    allowFailedIntercepts: true,
  },
});

Maximum security

const scramjet = new ScramjetController({
  flags: {
    strictRewrites: true,
    rewriterLogs: false,
    captureErrors: true,
    cleanErrors: true,
    sourcemaps: false,
    scramitize: true,
    syncxhr: false,
    serviceworkers: false,
    destructureRewrites: true,
    allowInvalidJs: false,
    allowFailedIntercepts: false,
  },
});

Modifying configuration at runtime

You can modify the configuration after initialization using the modifyConfig() method:

const scramjet = new ScramjetController({
  prefix: '/scramjet/',
  flags: {
    strictRewrites: true,
  },
});

await scramjet.init();

// Later, modify the configuration
await scramjet.modifyConfig({
  flags: {
    rewriterLogs: true,
    interceptDownloads: true,
  },
});

Configuration changes are persisted to IndexedDB and synchronized with the service worker.

Debugging flag issues

If you’re experiencing issues with specific flags, enable rewriterLogs to see detailed information:

const scramjet = new ScramjetController({
  flags: {
    rewriterLogs: true,
  },
});

await scramjet.init();

// Open browser console to see detailed rewriter logs

You can also check which flags are currently active:

import { config } from '@/shared/index';

console.log('Current flags:', config.flags);
console.log('Site flags:', config.siteFlags);

Related guides

Basic setup

Learn the basics of setting up Scramjet

Event handling

Handle events triggered by different flags