Repository navigation
Bootstrap a new app
The quickest way to get a working frontend utilizing Scramjet is create-proxy-app. It scaffolds a small Express server that uses @mercuryworkshop/proxy-bootstrap to serve Scramjet, the Scramjet controller, a transport, and a Wisp server. You don't have to wire any of these together yourself. In turn you get a nice example frontend, without any frameworks, to get you started.
If you already have a site and want to add Scramjet to it, see Install into an existing app instead.
- Node.js 22
- npm, pnpm, yarn, or bun
- Network access to
registry.npmjs.orgwhen the server starts (see How the bootstrap works)
npx create-proxy-app
cd my-proxy
npm install
npm run devOpen http://localhost:3030, type a URL or search term into the box, and the page loads inside scramjet
my-proxy/
├── package.json # The package information for your frontend
├── server.js # Express + proxy-bootstrap
└── public/
├── index.html # The frontend's entry point and UI (search box + iframe)
├── index.js # Creates the controller and frame
├── index.css # The stylesheet for the UI
├── credits.html # Credits and licensing info for Scramjet
└── icon.png # Your frontend's icon
This section covers important details about functions or lines your frontend may use or has. Sorted by name/folder.
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();
});
app.use(express.static("public"));
const server = http.createServer(app);
server.on("upgrade", routeUpgrade);
server.listen(3030, () => {
console.log("Server is running on port 3030");
});-
bootstrap()downloads the client-side files and returns two handlers. -
routeRequest(req, res)serves the service worker, the bootstrap script, and the Scramjet, controller, utils, and transport bundles. It returnstruewhen it handled the request. -
-
reqis the HTTP message request, and anhttp.IncomingMessageobject.
-
-
-
resis the server's HTTP response, and anhttp.ServerResponseobject.
-
-
routeUpgrade(req, socket, head)handles WebSocket upgrades on/wisp/and passes them to the built-in Wisp server. -
-
reqis the HTTP message request, and anhttp.IncomingMessageobject.
-
-
-
socketis the live TCP connection for the client. It is typically passed torouteUpgrade()as anet.Socketobject, but can be of any type.
-
-
-
headis the buffer containing the first chunk of data that was recieved before the upgrade handshake.
-
The important line is:
<script src="/bootstrap-init.js"></script>This script is generated by the bootstrap server. It defines a global initBootstrap() function.
The template also contains <meta name="robots" content="noindex" />, which keeps search engines from indexing the proxy. Remove it if you want your main domain to show up in search results.
const controller = await initBootstrap();
const frame = controller.createFrame(document.getElementById("sj-frame"), {
plugins: [
new $scramjetUtils.HttpCachePlugin(),
new $scramjetUtils.UrlWatcherPlugin((url) => {
frameUrl.textContent = url;
}),
new $scramjetUtils.CatchEscapedLinksPlugin(
(url) => new URL(`/?goto=${encodeURIComponent(url.href)}`, location.origin)
),
],
});
frame.go("https://example.com");initBootstrap() does four things:
- Registers the service worker at
/sw.js. - Loads the Scramjet, controller, and utils bundles. These add the globals
$scramjet,$scramjetController, and$scramjetUtils. - Creates a transport (libcurl by default) pointed at
ws(s)://<your host>/wisp/. - Creates and returns a
Controller.
controller.createFrame() attaches Scramjet to an <iframe>, and frame.go(url) navigates it. For a list of the plugins in $scramjetUtils, see Configure Scramjet - Plugins.
@mercuryworkshop/proxy-bootstrap does not bundle Scramjet. Every time the server starts, or bootstrap() runs, it:
- Looks up the latest version of
@mercuryworkshop/scramjet-controlleron npm. This package contains both the controller and also downloads the@mercuryworkshop/scramjetit requires. - Downloads that package.
- Downloads the latest
@mercuryworkshop/scramjet-utils. - Downloads the latest compatible transport (
@mercuryworkshop/libcurl-transportby default).
The downloaded packages are installed at node_modules/@mercuryworkshop/proxy-bootstrap/dist/.downloads/. The controller and utils downloads are skipped if the version on disk is already the latest.
This makes the majority of maintenance automatic:
- New compatible Scramjet releases are picked up automatically on restart.
- The server must be able to reach
registry.npmjs.orgat startup. - To pin exact versions or bundle the files yourself, use the manual setup instructions in Install into an existing app.
-
Change the port: edit
server.listen(3030, ...)inserver.js. Replace3030with your desired port. -
Change the UI: edit the files in
public/to your liking. Keep the/bootstrap-init.jsscript tag and theinitBootstrap()call. -
Change bootstrap options: pass your desired options to
bootstrap({...})inserver.js. See Configure Scramjet - Bootstrap options. - Change Scramjet behavior (flags, plugins, hooks): see Configure Scramjet.
The scaffolded app is a standard Node server. Run npm start behind any process manager or reverse proxy. When running in production environments, all of these are best practice:
-
HTTPS is required in production. Service workers only register on secure origins (
localhostis an exception). -
Your reverse proxy must forward WebSocket upgrades on
/wisp/. For example, if you're using nginx, add this to your config:location /wisp/ { proxy_pass http://127.0.0.1:3030; # Replace 3030 with your desired port proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; }
-
Don't cache
/sw.jstoo aggressively at a CDN, or clients will keep running an outdated service worker.