Repository navigation
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.
| 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.
-
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.
npm install @mercuryworkshop/proxy-bootstrapbootstrap() 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.
<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.
-
Only the libcurl transport is served.
routeRequestdoesn't currently serveepoxyClientPath, sotransport: "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/.routeUpgradeonly accepts upgrades on/wisp/, whateverwispPathis 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.
# 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 serverYou 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).
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).
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.
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.
Note: The ESM builds of
@mercuryworkshop/scramjetand@mercuryworkshop/scramjet-controller(scramjet-external.mjsandcontroller-external.mjs) are stubs. They just re-export whatever the IIFE bundles put onglobalThis.$scramjetandglobalThis.$scramjetController. Even with a bundler, you still have to load/scramjet/scramjet.jsand/controller/controller.api.jswith<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.
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 runningEach 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.
-
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.jsis served from the root and that you wait fornavigator.serviceWorker.readybefore you create the controller. -
Controller is not ready. Callawait controller.wait()beforecreateFrame(). -
A version mismatch error at startup. The controller and core versions don't match. Install the
@mercuryworkshop/scramjetversion listed in your controller'spackage.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 forwardsUpgradeheaders.