> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mercuryworkshop/scramjet/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```javascript theme={null}
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.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    serviceworkers: true,
  },
});
```

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

### syncxhr

**Type:** `boolean`
**Default:** `false`

Enables synchronous XMLHttpRequest support.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    syncxhr: true,
  },
});
```

<Note>
  Synchronous XHR is deprecated in modern browsers. Enable this only for legacy compatibility.
</Note>

### strictRewrites

**Type:** `boolean`
**Default:** `true`

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

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    strictRewrites: true,
  },
});
```

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

### rewriterLogs

**Type:** `boolean`
**Default:** `false`

Enables verbose logging from the URL rewriter for debugging purposes.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    rewriterLogs: true,
  },
});
```

### captureErrors

**Type:** `boolean`
**Default:** `true`

Captures and handles JavaScript errors within proxied contexts.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    captureErrors: true,
  },
});
```

### cleanErrors

**Type:** `boolean`
**Default:** `false`

Cleans error stack traces to remove proxy-related information.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    cleanErrors: true,
  },
});
```

### scramitize

**Type:** `boolean`
**Default:** `false`

Enables additional obfuscation and protection mechanisms.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    scramitize: true,
  },
});
```

### sourcemaps

**Type:** `boolean`
**Default:** `true`

Enables source map support for better debugging of rewritten JavaScript.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    sourcemaps: true,
  },
});
```

### destructureRewrites

**Type:** `boolean`
**Default:** `false`

Uses destructuring patterns in rewritten code for potentially better performance.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    destructureRewrites: true,
  },
});
```

### interceptDownloads

**Type:** `boolean`
**Default:** `false`

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

```javascript theme={null}
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](/guides/event-handling) for more details on download interception.

### allowInvalidJs

**Type:** `boolean`
**Default:** `true`

Allows execution of JavaScript that may not parse correctly.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    allowInvalidJs: true,
  },
});
```

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

### allowFailedIntercepts

**Type:** `boolean`
**Default:** `true`

Allows requests to proceed even if interception fails.

```javascript theme={null}
const scramjet = new ScramjetController({
  flags: {
    allowFailedIntercepts: true,
  },
});
```

## Site-specific flag overrides

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

```javascript theme={null}
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,
    },
  },
});
```

<Tip>
  Site-specific flags are useful when certain websites require different settings for compatibility.
</Tip>

## Common configuration presets

Here are some common flag configurations for different use cases:

<Tabs>
  <Tab title="Development">
    ```javascript theme={null}
    const scramjet = new ScramjetController({
      flags: {
        strictRewrites: true,
        rewriterLogs: true,
        captureErrors: true,
        cleanErrors: false,
        sourcemaps: true,
        allowInvalidJs: true,
        allowFailedIntercepts: true,
      },
    });
    ```
  </Tab>

  <Tab title="Production">
    ```javascript theme={null}
    const scramjet = new ScramjetController({
      flags: {
        strictRewrites: true,
        rewriterLogs: false,
        captureErrors: true,
        cleanErrors: true,
        sourcemaps: false,
        scramitize: true,
        allowInvalidJs: true,
        allowFailedIntercepts: true,
      },
    });
    ```
  </Tab>

  <Tab title="Maximum compatibility">
    ```javascript theme={null}
    const scramjet = new ScramjetController({
      flags: {
        strictRewrites: false,
        rewriterLogs: false,
        captureErrors: true,
        cleanErrors: true,
        sourcemaps: true,
        syncxhr: true,
        serviceworkers: true,
        allowInvalidJs: true,
        allowFailedIntercepts: true,
      },
    });
    ```
  </Tab>

  <Tab title="Maximum security">
    ```javascript theme={null}
    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,
      },
    });
    ```
  </Tab>
</Tabs>

## Modifying configuration at runtime

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

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

await scramjet.init();

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

<Note>
  Configuration changes are persisted to IndexedDB and synchronized with the service worker.
</Note>

## Debugging flag issues

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

```javascript theme={null}
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:

```javascript theme={null}
import { config } from '@/shared/index';

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

## Related guides

<CardGroup cols={2}>
  <Card title="Basic setup" icon="rocket" href="/guides/basic-setup">
    Learn the basics of setting up Scramjet
  </Card>

  <Card title="Event handling" icon="bolt" href="/guides/event-handling">
    Handle events triggered by different flags
  </Card>
</CardGroup>