Skip to content

Bootstrap a new app

xmb9 edited this page Nov 14, 2026 · 2 revisions

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.

Requirements

  • Node.js 22
  • npm, pnpm, yarn, or bun
  • Network access to registry.npmjs.org when the server starts (see How the bootstrap works)

Create the project

npx create-proxy-app
cd my-proxy
npm install
npm run dev

Open http://localhost:3030, type a URL or search term into the box, and the page loads inside scramjet

What you get

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

Explanations

This section covers important details about functions or lines your frontend may use or has. Sorted by name/folder.

server.js

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 returns true when it handled the request.
    • req is the HTTP message request, and an http.IncomingMessage object.
    • res is the server's HTTP response, and an http.ServerResponse object.
  • routeUpgrade(req, socket, head) handles WebSocket upgrades on /wisp/ and passes them to the built-in Wisp server.
    • req is the HTTP message request, and an http.IncomingMessage object.
    • socket is the live TCP connection for the client. It is typically passed to routeUpgrade() as a net.Socket object, but can be of any type.
    • head is the buffer containing the first chunk of data that was recieved before the upgrade handshake.

public/index.html

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.

public/index.js

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:

  1. Registers the service worker at /sw.js.
  2. Loads the Scramjet, controller, and utils bundles. These add the globals $scramjet, $scramjetController, and $scramjetUtils.
  3. Creates a transport (libcurl by default) pointed at ws(s)://<your host>/wisp/.
  4. 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.

How the bootstrap works

@mercuryworkshop/proxy-bootstrap does not bundle Scramjet. Every time the server starts, or bootstrap() runs, it:

  1. Looks up the latest version of @mercuryworkshop/scramjet-controller on npm. This package contains both the controller and also downloads the @mercuryworkshop/scramjet it requires.
  2. Downloads that package.
  3. Downloads the latest @mercuryworkshop/scramjet-utils.
  4. Downloads the latest compatible transport (@mercuryworkshop/libcurl-transport by 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.org at startup.
  • To pin exact versions or bundle the files yourself, use the manual setup instructions in Install into an existing app.

Customizing

  • Change the port: edit server.listen(3030, ...) in server.js. Replace 3030 with your desired port.
  • Change the UI: edit the files in public/ to your liking. Keep the /bootstrap-init.js script tag and the initBootstrap() call.
  • Change bootstrap options: pass your desired options to bootstrap({...}) in server.js. See Configure Scramjet - Bootstrap options.
  • Change Scramjet behavior (flags, plugins, hooks): see Configure Scramjet.

Deploying

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 (localhost is 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.js too aggressively at a CDN, or clients will keep running an outdated service worker.

Clone this wiki locally