How elouangrimm/srv-it works
1. Project shape
- srv-it is a small Node.js CLI package with one main runtime process.
- The executable entrypoint is bin/srv.js, which hands off to the CLI layer in src/cli.js.
- The core behavior lives in src/server.js, with configuration loading/merging in src/config.js.
2. Top-level flow
- A user runs the CLI from a terminal.
- The CLI resolves the target folder, merges config sources, then starts the server.
- The server serves static files, optionally opens a browser, and enables live reload/watch behavior.
3. Configuration architecture
- Config can come from multiple layers: built-in defaults, global ~/.srvrc.json, project srv.config.json, an explicit --config file, and CLI flags.
- CLI flags always win over file-based config.
- The repo includes srv.config.example.json as a template for per-project defaults.
4. Static file serving boundary
- The server is centered on a single document root: the current directory or a path passed on the command line.
- It serves files directly from disk and treats the folder itself as the content source.
- This is not an app framework; it is a file server with a few behaviors layered on top.
5. Route handling and fallbacks
- If a requested path maps to a real file, that file is served.
- If a folder contains index.html, that file is preferred.
- With --single, unknown routes fall back to index.html, which supports SPA-style client routing.
- If there is no index file and directory listing is enabled, a generated listing page is returned instead.
6. Live reload subsystem
- The server injects a small browser client into served HTML pages for live reload.
- File watching drives updates back to the browser over a websocket-style channel.
- CSS changes are treated specially: they refresh styles without a full page reload unless --no-css-inject is set.
7. Watcher behavior and resilience
- Watch mode can include extra paths via repeated --watch flags.
- Ignore rules can be added via --ignore, and some paths are always excluded, notably .git and node_modules.
- The implementation is defensive: if the OS watcher limit is reached (ENOSPC), the server keeps serving files but disables live reload instead of crashing.
8. Directory listing and presentation
- When a directory has no index.html, srv-it can render a styled directory listing page.
- The listing style is configurable with presets like midnight and paper.
- Custom styling can also be supplied through --style-css.
9. Network and transport options
- The server binds to a configurable host and port, defaulting to 0.0.0.0:3000.
- HTTPS is optional and driven by --ssl-cert, --ssl-key, and --ssl-pass.
- CORS can be enabled with --cors, making the server usable from other origins during development.
10. Operational UX
- The CLI includes browser auto-open behavior, request logging control, and startup verbosity controls.
- --open can open / or a specific path in the browser.
- --no-request-logging and --log-level adjust how chatty the tool is in the terminal.
11. Repository boundaries
- There is no separate frontend app, database, or background worker.
- The architecture is intentionally narrow: CLI parsing, config resolution, file serving, watching, and browser reload messaging.
- That makes the main diagram a single Node process with disk I/O, terminal I/O, and browser-facing HTTP/WebSocket traffic.
12. Packaging and delivery
- The package is meant for npm installation and global CLI use.
- .github/workflows/npm-publish-github-packages.yml indicates automated publishing/distribution from GitHub Actions.
Main entry points: server.js Server · config.js Config · cli.js CLI · srv.js srv.js
Components 15
CLI Runtime
The npm-installed command and its request/config/server execution path.
Config Layer
Sources and merging logic for runtime options.
- Config · Combines defaults, files, and flags into final settings.
src/config.js - Defaults · Base option values used when no external config is provided.
- Global rc · Optional per-user settings from ~/.srvrc.json.
- Project cfg · Per-repository settings from srv.config.json.
srv.config.example.json - CLI flags · Command-line overrides such as watch, open, cors, ssl, and logging.
File Server
Static file serving, directory handling, and live reload behavior.
- Server · Main process that serves files and coordinates reload/watch behavior.
src/server.js - Routing · Maps requests to files, index.html, SPA fallback, or listings.
- Directory list · Generates styled listings when a directory has no index file.
- Themes · Listing styling presets and custom CSS injection.
- Reload client · Injected browser-side code that listens for file change events.
- Watcher · Observes the document root and extra paths for changes.
- HTTP/WS · Serves content over HTTP/HTTPS and pushes reload events over a websocket-style channel.
Delivery
Packaging and automated publishing.
- Publish workflow · Automated npm/package publishing via GitHub Actions.
.github/workflows/npm-publish-github-packages.yml
Connections 16
- srv.js → CLI: invoke · The executable hands off to the CLI layer.
- CLI → Config: load/merge · CLI resolves config sources and final options.
- Defaults → Config: base · Built-in defaults seed the configuration.
- Global rc → Config: merge · User-level config is layered in.
- Project cfg → Config: merge · Project config contributes repository defaults.
- CLI flags → Config: override · CLI flags take precedence over file-based config.
- CLI → Server: start · CLI launches the server with the resolved options.
- Server → Routing: serve files · Server delegates request path resolution to file routing logic.
- Routing → Directory list: fallback · Directories without index.html can render a listing.
- Directory list → Themes: theme · Listings use presets or custom CSS.
- Server → Reload client: inject · HTML responses can include the browser reload client.
- Server → Watcher: watch · Filesystem changes drive live reload behavior.
- Watcher → Reload client: notify · Change events are forwarded to connected browsers.
- Server → HTTP/WS: http/https · Content is served over the configured network transport.
- Reload client → HTTP/WS: ws channel · Browser client communicates over a websocket-style channel.
- Publish workflow → srv.js: ship CLI · Release workflow publishes the installable command package.