s4d 0.1.0

package/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2024 Morris Brodersen <mb@morrisbrodersen.de>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# s4d
+
+Minimal web development server with live reload.
+
+## Installation
+
+```sh
+npm install s4d --save-dev # project local installation (preferred)
+npm install s4d --global # global installation
+```
+
+## Usage
+
+```
+s4d [options] <webroot>
+
+  --help, -h      Show this help.
+  --host <host>   Set hostname. Default is "localhost".
+                  Set "0.0.0.0" to expose over network.
+  --port <port>   Set port. Default is 8080.
+  --spa           Single-page application mode.
+                  Serves /index.html for URLs that cannot be resolved to a file.
+```
+
+Examples:
+
+```sh
+s4d public
+s4d --port 3000 public
+s4d --port 3000 --spa public
+s4d --port 3000 --host 0.0.0.0 --spa public # Expose over network
+```
+
+When installed locally in a project, run with `npx s4d [args...]`,
+unless running from an npm script.
+
+## Live Reload Behavior
+
+When a file under webroot is modified,
+attempts to reload stylesheets and images in-place
+if they match the modified file.
+In all other cases, a hard page reload is triggered.

package/dist/DevServer.d.ts

@@ -0,0 +1,39 @@
+import * as fs from 'fs';
+import * as http from 'http';
+import WebSocket, { WebSocketServer } from 'ws';
+export interface DevServerOptions {
+    webroot: string;
+    port: number;
+    host?: string;
+    spa?: boolean;
+}
+export declare class DevServer {
+    protected webroot: string;
+    protected port: number;
+    protected host?: string;
+    protected spa?: boolean;
+    protected server: http.Server;
+    protected webSocketServer: WebSocketServer;
+    protected fileWatcher?: fs.FSWatcher;
+    protected fileCache: Map<any, any>;
+    protected webSockets: Set<WebSocket>;
+    constructor(options: DevServerOptions);
+    static cli(argv: string[]): Promise<1 | undefined>;
+    static help(): string;
+    start(): Promise<void>;
+    startServer(): Promise<void>;
+    getBaseURL(): string;
+    handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
+    startWatching(): Promise<void>;
+    broadcast(message: Record<string, unknown>): void;
+    transformFileContents(file: string, contents: string | Buffer): Promise<string | Buffer>;
+    getClientScript(): string;
+    resolveFileCached(file: string): Promise<any>;
+    resolveFile(file: string): Promise<{
+        contents: string | Buffer;
+        contentType: string;
+        version: string;
+    }>;
+    invalidateFile(file: string): void;
+    close(): Promise<void>;
+}

package/dist/DevServer.js

@@ -0,0 +1,321 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as http from 'http';
+import mime from 'mime';
+import * as path from 'path';
+import WebSocket, { WebSocketServer } from 'ws';
+export class DevServer {
+    webroot;
+    port;
+    host;
+    spa;
+    server;
+    webSocketServer;
+    fileWatcher;
+    fileCache = new Map();
+    webSockets = new Set();
+    constructor(options) {
+        this.webroot = options.webroot;
+        this.port = options.port;
+        this.host = options.host;
+        this.spa = options.spa;
+        this.server = http.createServer((req, res) => this.handleRequest(req, res));
+        this.webSocketServer = new WebSocketServer({ server: this.server });
+        this.webSocketServer.on('connection', (webSocket) => this.webSockets.add(webSocket));
+    }
+    static async cli(argv) {
+        for (let i = 0; i < argv.length; ++i) {
+            switch (argv[i]) {
+                case '-h':
+                case '--help':
+                    console.log(this.help());
+                    return;
+            }
+        }
+        let webroot;
+        let port = 8080;
+        let host = 'localhost';
+        let spa = false;
+        try {
+            for (let i = 0; i < argv.length; ++i) {
+                switch (argv[i]) {
+                    case '--port':
+                        if (i + 1 >= argv.length) {
+                            throw new Error('--port requires an argument');
+                        }
+                        port = parseInt(argv[++i], 10);
+                        if (!(port >= 0 && port <= 65535)) {
+                            throw new Error(`Invalid port "${port}"`);
+                        }
+                        break;
+                    case '--host':
+                        if (i + 1 >= argv.length) {
+                            throw new Error('--host requires an argument');
+                        }
+                        host = argv[++i];
+                    case '--spa':
+                        spa = true;
+                        break;
+                    default:
+                        if (webroot) {
+                            throw new Error(`Unexpected argument "${argv[i]}"`);
+                        }
+                        webroot = argv[i];
+                }
+            }
+            if (!webroot) {
+                throw new Error('Webroot is required');
+            }
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}\n`);
+            console.error(this.help());
+            return 1;
+        }
+        const devServer = new DevServer({ webroot, port, host, spa });
+        await devServer.start();
+        console.error(`Development server started: ${devServer.getBaseURL()}`);
+    }
+    static help() {
+        return `s4d [options] <webroot>
+
+  --help, -h      Show this help.
+  --host <host>   Set hostname. Default is "localhost".
+                  Set "0.0.0.0" to expose over network.
+  --port <port>   Set port. Default is 8080.
+  --spa           Single-page application mode.
+                  Serves /index.html for URLs that cannot be resolved to a file.
+
+`;
+    }
+    async start() {
+        try {
+            await this.startWatching();
+            await this.startServer();
+        }
+        catch (err) {
+            await this.close();
+            throw err;
+        }
+    }
+    async startServer() {
+        return new Promise((resolve, reject) => {
+            this.server.on('listening', () => {
+                const address = this.server.address();
+                if (address && typeof address !== 'string') {
+                    this.port = address.port;
+                    resolve();
+                }
+                else {
+                    throw new Error(`Unexpected server address: ${address}`);
+                }
+            });
+            this.server.on('error', reject);
+            this.server.listen(this.port, this.host);
+        });
+    }
+    getBaseURL() {
+        const hostname = !this.host || this.host === '0.0.0.0' ? 'localhost' : this.host;
+        return `http://${hostname}:${this.port}`;
+    }
+    async handleRequest(req, res) {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.setHeader('content-type', 'text/plain');
+            res.writeHead(405);
+            res.end('Method not allowed');
+            return;
+        }
+        const url = new URL(req.url ?? '/', this.getBaseURL());
+        try {
+            const file = path.join(this.webroot, path.resolve('.', url.pathname));
+            const { contents, contentType, version } = await this.resolveFileCached(file);
+            if (req.headers['if-none-match'] === version) {
+                res.writeHead(304);
+                res.end();
+                return;
+            }
+            res.setHeader('content-type', contentType);
+            res.setHeader('etag', version);
+            res.writeHead(200);
+            if (req.method === 'HEAD') {
+                res.end();
+            }
+            else {
+                res.end(contents);
+            }
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                res.setHeader('content-type', 'text/plain');
+                res.writeHead(404);
+                res.end('Not found');
+            }
+            else {
+                console.error(err);
+                res.setHeader('content-type', 'text/plain');
+                res.writeHead(500);
+                res.end(`Internal server error: ${err.message}`);
+            }
+        }
+    }
+    async startWatching() {
+        this.fileWatcher = fs.watch(this.webroot, { recursive: true });
+        this.fileWatcher.on('change', (_, filename) => {
+            if (typeof filename === 'string') {
+                this.invalidateFile(path.join(this.webroot, filename));
+                this.broadcast({ type: 'change', url: filename });
+            }
+        });
+    }
+    broadcast(message) {
+        for (const webSocket of this.webSockets) {
+            if (webSocket.readyState === WebSocket.OPEN) {
+                webSocket.send(JSON.stringify(message));
+            }
+            else {
+                this.webSockets.delete(webSocket);
+                webSocket.terminate();
+            }
+        }
+    }
+    async transformFileContents(file, contents) {
+        const ext = path.extname(file);
+        if (ext === '.html') {
+            return `${contents}<script type="module" src="__DEV__.js"></script>`;
+        }
+        return contents;
+    }
+    getClientScript() {
+        return `if (!navigator.webdriver) {
+      const wsProtocol = location.protocol === 'http:' ? 'ws://' : 'wss://';
+      const socket = new WebSocket(wsProtocol + location.host);
+
+      const hotURLs = new Set();
+
+      socket.addEventListener('message', (message) => {
+        if (!message.data) return;
+
+        const data = JSON.parse(message.data);
+
+        if (hotURLs.has(data.url)) {
+          return;
+        }
+
+        if (hotURLs.size === 0) {
+          setTimeout(() => hotURLs.clear(), 50);
+        }
+
+        hotURLs.add(data.url);
+
+        let reload = true;
+
+        // Hot reload stylesheets
+        document.querySelectorAll('link[rel=stylesheet]').forEach((el) => {
+          const href = el.getAttribute('href');
+
+          if (endsWithURL(data.url, href)) {
+            reload = false;
+
+            el.setAttribute('href', href);
+          }
+        });
+
+        // Hot reload images
+        const refetchImages = new Map();
+
+        document.querySelectorAll('img').forEach(async (el) => {
+          const src = el.getAttribute('src');
+          const srcset = el.getAttribute('srcset');
+
+          if (
+            src && endsWithURL(data.url, src) ||
+            srcset && containsURL(srcset, data.url)
+          ) {
+            reload = false;
+
+            let promise = refetchImages.get(data.url);
+
+            if (!promise) {
+              promise = fetch(data.url, { cache: 'reload' });
+              refetchImages.set(data.url, promise);
+            }
+
+            await promise;
+
+            if (src) el.setAttribute('src', src);
+            if (srcset) el.setAttribute('srcset', srcset);
+          }
+        });
+
+        // Otherwise, reload page
+        if (reload) {
+          location.reload();
+        }
+      });
+
+      socket.addEventListener('open', () => {
+        console.info('Development server connected');
+      });
+
+      socket.addEventListener('close', () => {
+        console.warn('Development server disconnected');
+      });
+    }
+
+    function endsWithURL(candidate, target) {
+      return candidate.endsWith(target.replace(/^\\.?\\//, ''));
+    }
+
+    function containsURL(candidate, target) {
+      return candidate.match(target.replace(/^\\.?\\//, ''));
+    }`;
+    }
+    async resolveFileCached(file) {
+        const cached = this.fileCache.get(file);
+        if (cached)
+            return cached;
+        const promise = this.resolveFile(file);
+        this.fileCache.set(file, promise);
+        return promise;
+    }
+    async resolveFile(file) {
+        if (file.match(/__DEV__\.js$/)) {
+            return {
+                contents: this.getClientScript(),
+                contentType: 'application/javascript',
+                version: '1',
+            };
+        }
+        let contents;
+        try {
+            const stat = await fs.promises.lstat(file);
+            if (stat.isDirectory()) {
+                file = path.join(file, 'index.html');
+            }
+            contents = await fs.promises.readFile(file);
+        }
+        catch (err) {
+            if (this.spa && err.code === 'ENOENT') {
+                file = path.join(this.webroot, 'index.html');
+                contents = await fs.promises.readFile(file);
+            }
+            else {
+                throw err;
+            }
+        }
+        contents = await this.transformFileContents(file, contents);
+        const contentType = mime.getType(file) ?? 'application/octet-stream';
+        const version = crypto.createHash('sha1').update(contents).digest('base64');
+        return { contents, contentType, version };
+    }
+    invalidateFile(file) {
+        this.fileCache.delete(file);
+        this.fileCache.delete(file.replace(/index.html$/, ''));
+        this.fileCache.delete(file.replace(/\/index.html$/, ''));
+    }
+    async close() {
+        this.server.close();
+        if (this.fileWatcher)
+            this.fileWatcher.close();
+    }
+}

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin.js

@@ -0,0 +1,11 @@
+import { DevServer } from './DevServer.js';
+DevServer.cli(process.argv.slice(2))
+    .then((exitCode) => {
+    if (typeof exitCode === 'number') {
+        process.exit(exitCode);
+    }
+})
+    .catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './DevServer.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './DevServer.js';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "s4d",
+  "version": "0.1.0",
+  "description": "Minimal web development server with live reload",
+  "keywords": [
+    "local",
+    "development",
+    "server"
+  ],
+  "author": "Morris Brodersen <mb@morrisbrodersen.de>",
+  "license": "ISC",
+  "homepage": "https://github.com/morris/s4d",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/morris/s4d.git"
+  },
+  "bugs": {
+    "url": "https://github.com/morris/s4d/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": "./dist/index.js",
+  "bin": "./dist/bin.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "format": "prettier --write .",
+    "format-check": "prettier --check .",
+    "lint": "eslint .",
+    "test": "playwright test",
+    "dev": "tsc --project tsconfig.build.json && node dist/bin.js test/fixture"
+  },
+  "dependencies": {
+    "mime": "^4.0.1",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.44.1",
+    "@types/node": "^20.11.30",
+    "@types/ws": "^8.5.10",
+    "@typescript-eslint/eslint-plugin": "^7.7.1",
+    "@typescript-eslint/parser": "^7.7.1",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.1",
+    "typescript": "^5.4.5"
+  }
+}