Skip to content

Install into an existing app

percs edited this page Nov 21, 2026 · 4 revisions

Install into an existing app

This page shows how to add Scramjet to a site or Node server you already have. There are two ways to do it:

  • Option A: Use proxy-bootstrap. Add two route handlers to your Node server. Scramjet's client files are downloaded and served for you. This is the easiest option.
  • Option B: Manual setup. Install the packages, serve the files yourself, and create the controller in your own code. Use this if you want pinned versions, a bundler (Vite, rspack, etc.), a static host, or a server that isn't Node.

If you're starting from nothing, Bootstrap a new app is faster, but doesn't give you control over what UI framework or bundler you want to use.

All packages and their purpose

Package name Package Runs in Purpose
Scramjet core @mercuryworkshop/scramjet Page + proxied frames Rewrites HTML, JS, and CSS, and sandboxes the proxied page
Controller @mercuryworkshop/scramjet-controller Page + service worker Connects your page, the service worker, and the frames to each other
Transport @mercuryworkshop/libcurl-transport or @mercuryworkshop/epoxy-transport Page Makes the real network requests over Wisp
Wisp server @mercuryworkshop/wisp-js (or any Wisp server) Your server Tunnels TCP over a WebSocket
Utils (optional) @mercuryworkshop/scramjet-utils Page Ready-made plugins: HTTP cache, URL watcher, and others

A request from a proxied frame follows this path: frame => service worker => controller (in your page) => transport => Wisp server => the real website.

Requirements

  • A secure origin. Service workers only work over HTTPS or on localhost.
  • The service worker must cover the proxy prefix. The default prefix is /~/sj/, so register the worker from the site root (/sw.js) so that its scope covers it.
  • A reachable Wisp server, either on the same server or a separate one.

Option A: Use proxy-bootstrap

1. Install

npm install @mercuryworkshop/proxy-bootstrap

2. Add the routes to your server

bootstrap() returns two handlers. Each one returns true if it handled the request. Call them before your own routes.

Express

import http from "node:http";
import express from "express";
import { bootstrap } from "@mercuryworkshop/proxy-bootstrap";

const { routeRequest, routeUpgrade } = await bootstrap();

const app = express();
app.use((req, res, next) => {
	if (routeRequest(req, res)) return;
	next();
});

// ...your existing routes and static files...

const server = http.createServer(app);
server.on("upgrade", (req, socket, head) => {
	if (routeUpgrade(req, socket, head)) return;
	// ...your own websocket handling, if any...
	socket.destroy();
});
server.listen(3030, () => {
	console.log("Server is running on port 3030");
});

Plain node:http

import http from "node:http";
import { bootstrap } from "@mercuryworkshop/proxy-bootstrap";

const { routeRequest, routeUpgrade } = await bootstrap();

const server = http.createServer((req, res) => {
	if (routeRequest(req, res)) return;
	// ...your handler...
});
server.on("upgrade", (req, socket, head) => {
	if (!routeUpgrade(req, socket, head)) socket.destroy();
});
server.listen(3030, () => {
	console.log("Server is running on port 3030");
});

With other server frameworks (Fastify, Koa, Hono on Node), the idea is the same: give the raw IncomingMessage and ServerResponse to routeRequest, and the raw upgrade arguments to routeUpgrade.

bootstrap() takes these routes for itself (all paths can be changed, see Bootstrap options):

Path Contents
/sw.js Generated service worker
/bootstrap-init.js Defines initBootstrap()
/controller/controller.{api,inject,sw}.js Controller bundles
/scram/scramjet.js, /scram/scramjet.wasm Scramjet core and rewriter
/scram/scramjet-utils.js Utils bundle
/clients/libcurl-client.js libcurl transport
/wisp/ (WebSocket) Wisp server

If one of your own routes already uses one of these paths, move one or the other.

3. Add it to your page

<script src="/bootstrap-init.js"></script>

<iframe id="proxy-frame"></iframe>

<script type="module">
	const controller = await initBootstrap();

	const frame = controller.createFrame(document.getElementById("proxy-frame"), {
		plugins: [new $scramjetUtils.HttpCachePlugin()],
	});

	frame.go("https://example.com");
</script>

That's all. initBootstrap() registers the service worker, loads the bundles, creates the transport, and returns a ready Controller.

Limitations

  • Only the libcurl transport is served. routeRequest doesn't currently serve epoxyClientPath, so transport: "epoxy" downloads Epoxy but the browser can't load it. "bare" isn't implemented yet. If you need Epoxy, use Option B.
  • Wisp always uses /wisp/. routeUpgrade only accepts upgrades on /wisp/, whatever wispPath is set to.
  • Packages are downloaded on every start. The server needs to reach the npm registry at startup. If you already have the same version of a package, it will not be re-downloaded. See How the bootstrap works.

Option B: Manual setup

1. Install

# client side
# controller requires the version of scramjet it needs, so you don't need to download it seperately
npm install @mercuryworkshop/scramjet-controller \ 
            @mercuryworkshop/libcurl-transport
# optional plugins
npm install @mercuryworkshop/scramjet-utils
# server side (if you host your own Wisp server)
npm install @mercuryworkshop/wisp-js # or any other Wisp server

You can use @mercuryworkshop/epoxy-transport instead of libcurl-transport. The controller checks the Scramjet version at runtime, so if you install Scramjet seperately, install a version that matches what your scramjet-controller version expects (see the controller's package.json).

2. Serve the static files

By default, the controller expects:

URL File
/scramjet/scramjet.js @mercuryworkshop/scramjet/dist/scramjet.js
/scramjet/scramjet.wasm @mercuryworkshop/scramjet/dist/scramjet.wasm
/controller/controller.inject.js @mercuryworkshop/scramjet-controller/dist/controller.inject.js
/controller/controller.sw.js @mercuryworkshop/scramjet-controller/dist/controller.sw.js

The simplest way to provide them is to serve both dist/ folders as-is. If you serve them somewhere else, update the paths in the controller config.

Express

import express from "express";
import { join } from "node:path";
import { scramjetPath } from "@mercuryworkshop/scramjet/path";
import { controllerPath } from "@mercuryworkshop/scramjet-controller/path";

app.use("/scramjet/", express.static(scramjetPath));
app.use("/controller/", express.static(controllerPath));

Vite (this is how packages/demo does it)

// vite.config.js
import { viteStaticCopy } from "vite-plugin-static-copy";
import { scramjetPath } from "@mercuryworkshop/scramjet/path";
import { controllerPath } from "@mercuryworkshop/scramjet-controller/path";

export default {
	plugins: [
		viteStaticCopy({
			structured: false,
			targets: [
				{ src: scramjetPath + "/*", dest: "scramjet" },
				{ src: controllerPath + "/*", dest: "controller" },
			],
		}),
	],
};

Static hosting: copy the two dist/ folders into your public directory as scramjet/ and controller/. When statically hosting, you also need an external Wisp server (step 4).

3. Add a service worker

Create /sw.js at the root of your site:

importScripts("/controller/controller.sw.js");

addEventListener("fetch", (e) => {
	if ($scramjetController.shouldRoute(e)) {
		e.respondWith($scramjetController.route(e));
	}
});

shouldRoute only returns true for requests under a frame's prefix (/~/sj/...), so the rest of your site's traffic isn't affected. If you already have a service worker, add these lines to it instead of creating a second one.

4. Run a Wisp server

Transports reach the internet through a Wisp server. To host one on your Node server with wisp-js:

import { server as wisp } from "@mercuryworkshop/wisp-js/server";

server.on("upgrade", (req, socket, head) => {
	if (req.url.startsWith("/wisp/")) {
		wisp.routeRequest(req, socket, head);
	} else {
		socket.destroy();
	}
});

You can also use any other Wisp-compatible server (for example epoxy-server, wisp-server-python, etc.) and point the transport at its URL.

For a list of Wisp server implementations, see wisp-protocol - Server Implementations.

5. Create the controller

Note: The ESM builds of @mercuryworkshop/scramjet and @mercuryworkshop/scramjet-controller (scramjet-external.mjs and controller-external.mjs) are stubs. They just re-export whatever the IIFE bundles put on globalThis.$scramjet and globalThis.$scramjetController. Even with a bundler, you still have to load /scramjet/scramjet.js and /controller/controller.api.js with <script> tags in your HTML before your bundle runs. Importing the packages alone does not include Scramjet in your bundle.

With a bundler, add the script tags first:

<script src="/scramjet/scramjet.js"></script>
<script src="/controller/controller.api.js"></script>
<script type="module" src="/main.js"></script>

Then use the imports in your own code:

import { Controller } from "@mercuryworkshop/scramjet-controller";
import LibcurlClient from "@mercuryworkshop/libcurl-transport";
import { HttpCachePlugin } from "@mercuryworkshop/scramjet-utils";

async function getServiceWorker() {
	const registration = await navigator.serviceWorker.register("/sw.js");
	await navigator.serviceWorker.ready;
	return navigator.serviceWorker.controller ?? registration.active;
}

const wispUrl =
	(location.protocol === "https:" ? "wss://" : "ws://") + location.host + "/wisp/";

const controller = new Controller({
	serviceworker: await getServiceWorker(),
	transport: new LibcurlClient({ wisp: wispUrl }),
	// config: { ... },          // optional, see Configure Scramjet
	// scramjetConfig: { ... },  // optional, see Configure Scramjet
});
await controller.wait();

const frame = controller.createFrame(document.getElementById("proxy-frame"), {
	plugins: [new HttpCachePlugin()],
});
frame.go("https://example.com");

Without a bundler, load the browser bundles with script tags and use the globals they define:

<script src="/scramjet/scramjet.js"></script>
<script src="/controller/controller.api.js"></script>
<script src="/libcurl/index.js"></script> <!-- @mercuryworkshop/libcurl-transport/dist/index.js -->
<script>
	const { Controller } = $scramjetController;
	const transport = new LibcurlTransport.LibcurlClient({ wisp: wispUrl });
	// ...same as above
</script>

You need controller.api.js for the script-tag setup, so serve it along with the other controller files.

6. Use the frame

frame.go("https://example.com"); // navigate
frame.back();
frame.forward();
frame.reload();

controller.createFrame(); // without an element, it creates a new <iframe> for you
controller.setTransport(otherTransport); // switch transports while running

Each Controller and each Frame gets its own random ID, and these form the URL prefix (/~/sj/<controllerId>/<frameId>/...). Cookies are shared by all frames and saved to IndexedDB.

Troubleshooting

  • Proxied pages show your own site or a 404. The service worker isn't controlling the page yet, or its scope doesn't cover /~/sj/. Make sure /sw.js is served from the root and that you wait for navigator.serviceWorker.ready before you create the controller.
  • Controller is not ready. Call await controller.wait() before createFrame().
  • A version mismatch error at startup. The controller and core versions don't match. Install the @mercuryworkshop/scramjet version listed in your controller's package.json.
  • The page loads but every request fails. The transport can't reach Wisp. Look in the network tab for the /wisp/ WebSocket, and check that your reverse proxy forwards Upgrade headers.