Skip to main content

​
Quickstart

This guide will walk you through setting up a basic Scramjet proxy. You’ll learn how to register a service worker, initialize the controller, and create a proxied iframe.

​
Setup overview

A Scramjet proxy requires two main components:
  1. Service worker - Intercepts and rewrites network requests
  2. Controller - Manages frames and communicates with the service worker
1

Create the service worker

Create a file called sw.js in your static directory:
sw.js
importScripts("/scramjet/scramjet.all.js");

const { ScramjetServiceWorker } = $scramjetLoadWorker();
const scramjet = new ScramjetServiceWorker();

async function handleRequest(event) {
  await scramjet.loadConfig();
  
  if (scramjet.route(event)) {
    return scramjet.fetch(event);
  }
  
  return fetch(event.request);
}

self.addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event));
});
This service worker intercepts all fetch requests. If a request matches Scramjet’s routing (based on the configured prefix), it’s proxied. Otherwise, it’s passed through normally.
2

Set up your HTML page

Create an HTML page that will load Scramjet and register the service worker:
index.html
<!DOCTYPE html>
<html>
  <head>
    <title>Scramjet Proxy</title>
  </head>
  <body>
    <div id="container"></div>
    <script src="/scramjet/scramjet.bundle.js"></script>
    <script src="/app.js"></script>
  </body>
</html>
3

Initialize Scramjet controller

Create app.js to register the service worker and set up the controller:
app.js
// Load the Scramjet controller
const { ScramjetController } = $scramjetLoadController();

// Create a new controller instance
const scramjet = new ScramjetController({
  prefix: "/scramjet/",
  codec: {
    encode: (url) => encodeURIComponent(url),
    decode: (url) => decodeURIComponent(url)
  },
  flags: {
    captureErrors: true,
    strictRewrites: true
  }
});

async function init() {
  // Register the service worker
  if ("serviceWorker" in navigator) {
    await navigator.serviceWorker.register("/sw.js", {
      scope: "/"
    });
    
    // Wait for the service worker to be ready
    await navigator.serviceWorker.ready;
  }
  
  // Initialize Scramjet
  await scramjet.init();
  
  // Create a proxied iframe
  const frame = scramjet.createFrame();
  document.getElementById("container").appendChild(frame.frame);
  
  // Navigate to a URL
  frame.go("https://example.com");
}

init();
The prefix option determines which URL paths are handled by Scramjet. In this example, any request to /scramjet/* will be proxied.
4

Serve the static files

Make sure the Scramjet static files are available at the configured paths:
  • /scramjet/scramjet.bundle.js
  • /scramjet/scramjet.all.js
  • /scramjet/scramjet.wasm.wasm
These files are in the dist directory of the @mercuryworkshop/scramjet package.
5

Test your setup

Start your web server and open the page in a browser. You should see example.com loaded in the iframe through the Scramjet proxy.

​
Configuration options

The ScramjetController accepts several configuration options:

​
Basic options

const scramjet = new ScramjetController({
  prefix: "/scramjet/",  // URL prefix for proxied requests
  codec: {
    encode: (url) => encodeURIComponent(url),
    decode: (url) => decodeURIComponent(url)
  },
  files: {
    wasm: "/scramjet.wasm.wasm",
    all: "/scramjet.all.js",
    sync: "/scramjet.sync.js"
  }
});

​
Feature flags

Control Scramjet’s behavior with flags: 
const scramjet = new ScramjetController({
  prefix: "/scramjet/",
  flags: {
    strictRewrites: true,      // Enforce strict URL rewriting
    captureErrors: true,        // Capture and clean errors
    sourcemaps: true,          // Enable source map support
    allowInvalidJs: true       // Allow pages with invalid JS
  }
});
Some flags like syncxhr and serviceworkers enable experimental features that may impact performance or compatibility.

​
Working with frames

Scramjet provides a ScramjetFrame class for managing proxied iframes: 
// Create a frame (Scramjet creates the iframe element)
const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);

// Or use an existing iframe element
const existingIframe = document.getElementById("myframe");
const frame = scramjet.createFrame(existingIframe);

// Navigate to a URL
frame.navigate("https://example.com");

​
URL encoding and decoding

You can encode and decode URLs using the controller: 
// Encode a URL for use in the proxy
const proxiedUrl = scramjet.encodeUrl("https://example.com");
// Returns: "/scramjet/https%3A%2F%2Fexample.com"

// Decode a proxied URL back to the original
const originalUrl = scramjet.decodeUrl(proxiedUrl);
// Returns: "https://example.com"

​
Using Workbox (optional)

For more advanced service worker routing, you can use Workbox:
sw.js
importScripts("/scramjet/scramjet.all.js");
import { registerRoute } from "workbox-routing";

const { ScramjetServiceWorker } = $scramjetLoadWorker();
const scramjet = new ScramjetServiceWorker();

registerRoute(
  ({ request }) => {
    return scramjet.route({ request });
  },
  async ({ event }) => {
    await scramjet.loadConfig();
    return scramjet.fetch(event);
  }
);
Workbox routing is useful if you’re building a PWA with offline support alongside your proxy functionality.

​
Next steps

Now that you have a working Scramjet setup, you can:
  • Customize the codec to implement custom URL encoding schemes
  • Add event listeners to handle navigation and downloads
  • Configure site-specific flags for better compatibility
  • Explore the TypeScript API documentation for advanced features

​
Common issues

If CAPTCHAs aren’t working, make sure you’re not hosting on a datacenter IP. Residential IPs work best for CAPTCHA-heavy sites like Google and YouTube.
Service workers require HTTPS in production environments (except for localhost). Make sure your site is served over HTTPS.