From abe5960a538105bf767314ffd5f0877996399c4f Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Thu, 9 Jul 2026 13:40:33 +0200 Subject: [PATCH] docs: add How it works section explaining the JSS wrapper split Answers 'is this a fork? a proxy?' up front: servejss is a thin launcher that translates serve-style flags into a jss start invocation and never touches requests. Spells out what lives in the wrapper (CLI, public-mode defaults, port switching, banner, child process) vs upstream JSS (all request handling and Solid features), so behavior issues get filed in the right repo. --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 70cd9be..f13bd26 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,25 @@ **servejss** is `serve` with superpowers: same simple interface, but you can write too. +## How it works + +servejss doesn't serve anything itself — it's a thin launcher for +[JSS](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer). +It translates `serve`-style flags into a `jss start` invocation, points it +at your directory in `--public` mode (no auth, WAC skipped), picks a free +port, prints the banner, and manages the child process. Every request is +handled by JSS. + +In practice that split means: + +- **servejss owns** the CLI, the serve-a-directory defaults (public mode, + live reload, git backend), port auto-switching, and the startup UX +- **JSS owns** everything about actual serving: GET/PUT/DELETE handling, + ETags and conditional requests, the git HTTP backend, and all Solid + protocol features — so issues about request behavior belong upstream +- `--solid` drops the public default and starts JSS as a full + authenticated Solid server (Solid-OIDC + WAC) + ## Install ```bash