ScramjetController

Main controller class for managing Scramjet instances

The ScramjetController class manages Scramjet instances, handles configuration, and provides frame creation. It extends EventTarget to support listening for global Scramjet events.

Constructor

Creates a new ScramjetController instance.

new ScramjetController(config: Partial<ScramjetInitConfig>)

config · Partial<ScramjetInitConfig> · required

Configuration options for Scramjet. See config types for details.

Show Common properties

prefix · string

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

flags · Partial<ScramjetFlags>

Feature flags to enable or disable Scramjet features

codec · { encode: Function, decode: Function }

Custom URL encoding/decoding functions

Example

const { ScramjetController } = $scramjetLoadController();

const scramjet = new ScramjetController({
  prefix: "/scramjet/",
  flags: {
    serviceworkers: false,
    syncxhr: false,
    strictRewrites: true,
    captureErrors: true
  }
});

Methods

init()

Initializes the controller by loading codecs, opening IndexedDB, and setting up message listeners.

async init(): Promise<void>

You must call init() before using other methods on the controller.

Example

await scramjet.init();

createFrame()

Creates a new ScramjetFrame instance for managing an iframe.

createFrame(frame?: HTMLIFrameElement): ScramjetFrame

frame · HTMLIFrameElement

Optional existing iframe element. If not provided, a new iframe is created.

Returns

A ScramjetFrame instance for managing the iframe.

Example

const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);
frame.go("https://example.com");

encodeUrl()

Encodes a real URL into a Scramjet-proxied URL.

encodeUrl(url: string | URL): string

url · string | URL · required

The real URL to encode

Returns

The encoded URL with the Scramjet prefix.

Example

const proxiedUrl = scramjet.encodeUrl("https://example.com");
// Returns: "/scramjet/https%3A%2F%2Fexample.com"

Only HTTP and HTTPS URLs are encoded. Other protocols are returned unchanged.

decodeUrl()

Decodes a Scramjet-proxied URL back to the real URL.

decodeUrl(url: string | URL): string

url · string | URL · required

The proxied URL to decode

Returns

The decoded real URL.

Example

const realUrl = scramjet.decodeUrl("/scramjet/https%3A%2F%2Fexample.com");
// Returns: "https://example.com"

modifyConfig()

Dynamically updates the Scramjet configuration.

async modifyConfig(newconfig: Partial<ScramjetInitConfig>): Promise<void>

newconfig · Partial<ScramjetInitConfig> · required

The configuration properties to update

Example

await scramjet.modifyConfig({
  flags: {
    captureErrors: false,
    strictRewrites: false
  }
});

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

addEventListener()

Adds an event listener for Scramjet global events.

addEventListener<K extends keyof ScramjetGlobalEvents>(
  type: K,
  listener: (event: ScramjetGlobalEvents[K]) => void,
  options?: boolean | AddEventListenerOptions
): void

type · 'download' · required

The event type to listen for

listener · Function · required

The callback function to execute when the event fires

options · boolean | AddEventListenerOptions

Event listener options

Example

scramjet.addEventListener("download", (event) => {
  console.log("Download intercepted:", event.download.filename);
  console.log("URL:", event.download.url);
});

Events

download

Fired when a download is intercepted by Scramjet.

interface ScramjetGlobalDownloadEvent extends Event {
  type: "download";
  download: ScramjetDownload;
}

See event types for the full ScramjetDownload interface.