Docs: Document config flow from servejss through JSS #121
Description
Problem
The config flow from servejss wrapper to JSS is undocumented and confusing:
servejss CLI (bin/jsserve.js)
↓ spawns child process with CLI args
JSS CLI (bin/jss.js)
↓ parses CLI args
config.js (loadConfig)
↓ merges defaults → file → env → CLI
server.js (createServer)
↓ extracts options into local vars
request object (via Fastify hook)
↓ scattered across properties
handlers (access config)
Issues:
-
Options asymmetry - servejss has different option names than JSS:
--live(servejss) →--live-reload(JSS)--read-only(servejss) →--read-only(JSS) ✓--solid(servejss) →--idp --conneg(JSS)
-
Lost options - some servejss options don't reach JSS:
--auth(servejss) → not passed to JSS--single(SPA mode) → not implemented
-
Implicit options - servejss always adds
--public:const jssArgs = ['start', '--root', dir, '--port', String(port), '--host', options.host, '--public'];
-
Config precedence unclear:
- What wins: CLI flag vs env var vs config file?
Proposed Solution
Create docs/CONFIG-FLOW.md:
# Configuration Flow
## Overview
JSS configuration flows through multiple layers with clear precedence:
\`\`\`
defaults (config.js)
→ config file (jss.config.json)
→ environment variables
→ CLI arguments (highest priority)
\`\`\`
## servejss → JSS Mapping
| servejss option | JSS equivalent | Notes |
|-----------------|----------------|-------|
| `--live` | `--live-reload` | Default: true in servejss |
| `--read-only` | `--read-only` | Direct mapping |
| `--solid` | `--idp --conneg` | Enables full Solid features |
| `--port` | `--port` | Direct mapping |
| (implicit) | `--public` | Always added by servejss |
## Environment Variables
| Variable | Config Key | Default |
|----------|------------|---------|
| `PORT` | `port` | 3000 |
| `DATA_ROOT` | `root` | ./data |
| `TOKEN_SECRET` | - | random |
| ... | ... | ... |
## Config File Format
\`\`\`json
{
"port": 3000,
"root": "./data",
"conneg": false,
"notifications": false,
"idp": false
}
\`\`\`Benefits
- Clear documentation for users and contributors
- Easier debugging of config issues
- Reduces confusion about option mapping
Priority
P2 - Medium priority, improves developer experience