Config types

Configuration type definitions for Scramjet

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}`);