Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ading2210/sandstone/llms.txt

Use this file to discover all available pages before exploring further.

Sandstone ships an example frontend in the example/ subdirectory. It is a complete browser-like UI built on top of the Sandstone library — complete with a URL bar, favicon fetching, a configurable Wisp endpoint, and an in-page JavaScript eval tool. Running the example is the fastest way to verify that your build works end-to-end and to experiment with Sandstone before integrating it into your own project.

​
Prerequisites

Complete the Build Sandstone from source guide before following these steps. The example frontend imports directly from ../dist/sandstone.mjs, so the main library must be compiled first.

​
Steps

1

Build the main library

If you have not already done so, build the main Sandstone bundles from the repository root:
npm run build:prod
See Build Sandstone from source for the full instructions.
2

Enter the example directory

cd example
3

Install example dependencies

The example has its own package.json with dependencies for the Express server and Wisp:
npm install
4

Build the example frontend

Compile the example’s webpack bundle. The production build also runs inline.mjs to produce a self-contained HTML file:
npm run build:prod
5

Start the server

Launch the Express web server:
npm run start
By default the server listens on port 5001. You can override this with the PORT environment variable:
PORT=8080 npm run start
6

Open the app in your browser

Navigate to http://localhost:5001 (or whichever port you configured). You should see the Sandstone browser UI.

​
What the example provides

The example app exposes the following UI elements, each backed by real logic in example/main.mjs:
  • URL bar — accepts full URLs; prepends https:// automatically when no scheme is provided
  • Favicon display — fetches the proxied page’s favicon through sandstone.libcurl.fetch and displays it next to the URL bar
  • Options panel — lets you change the Wisp WebSocket endpoint at runtime without reloading the page
  • JS eval tool — lets you run arbitrary JavaScript inside the proxied frame via main_frame.eval_js()
  • Version indicator — shows the compiled Sandstone version and short git hash

​
Running both watchers at once

From the repository root, you can start watch mode for both the main library and the example frontend simultaneously using the dev:all script: 
npm run dev:all
This uses concurrently to run npm run dev in the root and npm run dev inside example/ at the same time. Any source change in either location triggers an automatic rebuild.

​
Wisp proxying

The Express server in example/server.mjs handles WebSocket upgrade events and routes them to the bundled Wisp server: 
server.on("upgrade", (request, socket, head) => {
  wisp.routeRequest(request, socket, head);
});
This means the example server acts as both a static file host and a local Wisp proxy endpoint. You do not need to run a separate Wisp server to use the example locally.

Build docs developers (and LLMs) love

Get started for freeTalk to us