Skip to main content
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: 
const scramjet = new ScramjetController({
  flags: {
    strictRewrites: true,
    rewriterLogs: true,
    captureErrors: true,
    cleanErrors: false,
    sourcemaps: true,
    allowInvalidJs: true,
    allowFailedIntercepts: true,
  },
});

​
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);

Basic setup

Learn the basics of setting up Scramjet

Event handling

Handle events triggered by different flags

Build docs developers (and LLMs) love

Get started for freeTalk to us