Config types

Scramjet uses a comprehensive configuration system to control behavior, feature flags, and URL encoding.

ScramjetInitConfig

The configuration interface for initializing Scramjet.

interface ScramjetInitConfig {
  prefix: string;
  globals: {
    wrapfn: string;
    wrappropertybase: string;
    wrappropertyfn: string;
    cleanrestfn: string;
    importfn: string;
    rewritefn: string;
    metafn: string;
    setrealmfn: string;
    pushsourcemapfn: string;
    trysetfn: string;
    templocid: string;
    tempunusedid: string;
  };
  files: {
    wasm: string;
    all: string;
    sync: string;
  };
  flags: Partial<ScramjetFlags>;
  siteFlags?: Record<string, Partial<ScramjetFlags>>;
  codec: {
    encode: (url: string) => string;
    decode: (url: string) => string;
  };
}

Properties

prefix

string

required

The URL prefix for proxied content. Default: /scramjet/

Show Example

prefix: "/scramjet/"

globals

object

required

Global variable names used by Scramjet’s runtime.

Show Properties

wrapfn

string

Default: $scramjet$wrap

wrappropertybase

string

Default: $scramjet__

wrappropertyfn

string

Default: $scramjet$prop

cleanrestfn

string

Default: $scramjet$clean

importfn

string

Default: $scramjet$import

rewritefn

string

Default: $scramjet$rewrite

metafn

string

Default: $scramjet$meta

setrealmfn

string

Default: $scramjet$setrealm

pushsourcemapfn

string

Default: $scramjet$pushsourcemap

trysetfn

string

Default: $scramjet$tryset

templocid

string

Default: $scramjet$temploc

tempunusedid

string

Default: $scramjet$tempunused

files

object

required

Paths to Scramjet bundle files.

Show Properties

wasm

string

Path to WASM file. Default: /scramjet.wasm.wasm

all

string

Path to full bundle. Default: /scramjet.all.js

sync

string

Path to sync bundle. Default: /scramjet.sync.js

flags

Partial<ScramjetFlags>

required

Feature flags to enable or disable Scramjet features. See ScramjetFlags below.

siteFlags

Record<string, Partial<ScramjetFlags>>

Per-site feature flag overrides. Keys are hostnames or URLs.

Show Example

siteFlags: {
  "example.com": {
    strictRewrites: false
  }
}

codec

object

required

URL encoding and decoding functions.

Show Properties

encode

(url: string) => string

Function to encode URLs. Default uses encodeURIComponent.

decode

(url: string) => string

Function to decode URLs. Default uses decodeURIComponent.

Example

const config: Partial<ScramjetInitConfig> = {
  prefix: "/scramjet/",
  flags: {
    serviceworkers: false,
    syncxhr: false,
    strictRewrites: true,
    captureErrors: true,
    sourcemaps: true
  },
  codec: {
    encode: (url) => btoa(url),
    decode: (url) => atob(url)
  }
};

ScramjetConfig

The internal configuration interface (extends ScramjetInitConfig with normalized types).

interface ScramjetConfig {
  prefix: string;
  globals: { /* ... */ };
  files: { /* ... */ };
  flags: ScramjetFlags;
  siteFlags: Record<string, Partial<ScramjetFlags>>;
  codec: {
    encode: string;
    decode: string;
  };
}

ScramjetConfig is the same as ScramjetInitConfig, except the codec functions are serialized as strings and flags is complete (not partial).

ScramjetFlags

Feature flags that control Scramjet’s behavior.

type ScramjetFlags = {
  serviceworkers: boolean;
  syncxhr: boolean;
  strictRewrites: boolean;
  rewriterLogs: boolean;
  captureErrors: boolean;
  cleanErrors: boolean;
  scramitize: boolean;
  sourcemaps: boolean;
  destructureRewrites: boolean;
  interceptDownloads: boolean;
  allowInvalidJs: boolean;
  allowFailedIntercepts: boolean;
};

Properties

serviceworkers

boolean

Enable service worker support. Default: false

Enabling this may cause compatibility issues with some sites.

syncxhr

boolean

Enable synchronous XMLHttpRequest support. Default: false

strictRewrites

boolean

Enable strict URL rewriting. Default: true

When enabled, invalid URLs will throw errors instead of being silently ignored.

rewriterLogs

boolean

Enable verbose rewriter logging. Default: false

captureErrors

boolean

Capture and handle errors from proxified code. Default: true

cleanErrors

boolean

Clean Scramjet internals from error stack traces. Default: false

scramitize

boolean

Enable scramitization feature. Default: false

sourcemaps

boolean

Enable source map support. Default: true

destructureRewrites

boolean

Enable destructuring in rewrites. Default: false

interceptDownloads

boolean

Intercept and emit events for downloads. Default: false

allowInvalidJs

boolean

Allow invalid JavaScript to pass through. Default: true

allowFailedIntercepts

boolean

Allow failed intercepts without throwing errors. Default: true

Example

const flags: Partial<ScramjetFlags> = {
  strictRewrites: true,
  captureErrors: true,
  sourcemaps: true,
  interceptDownloads: true,
  cleanErrors: false
};

const scramjet = new ScramjetController({
  prefix: "/scramjet/",
  flags
});

ScramjetVersionInfo

Version information for the current Scramjet build.

interface ScramjetVersionInfo {
  /** The git commit hash that this build was created from */
  build: string;
  /** The semantic version */
  version: string;
}

Example

console.log(`Scramjet v${$scramjetVersion.version}`);
console.log(`Build: ${$scramjetVersion.build}`);

Factory Functions

Window Context

Service Worker Context

Types & Interfaces

ScramjetInitConfig

Properties

Example

ScramjetConfig

ScramjetFlags

Properties

Example

ScramjetVersionInfo

Example

Build docs developers (and LLMs) love

Factory Functions

Window Context

Service Worker Context

Types & Interfaces

​ScramjetInitConfig

​Properties

​Example

​ScramjetConfig

​ScramjetFlags

​Properties

​Example

​ScramjetVersionInfo

​Example

Build docs developers (and LLMs) love

ScramjetInitConfig

Properties

Example

ScramjetConfig

ScramjetFlags

Properties

Example

ScramjetVersionInfo

Example