feat: interactive JSON / JSON5 mode selector at build time

Lets the operator pick between strict JSON (legacy) and JSON5 for every
configuration file consumed by Nitro and the renderer.

- scripts/configure-json.mjs: interactive prompt (JSON5 recommended),
  with --if-missing and --non-interactive flags for CI use
- package.json: yarn configure / prestart / prebuild hooks
- vite.config.mjs: reads .nitro-build.json (or NITRO_JSON_MODE env) and
  injects the compile-time constant __NITRO_JSON_MODE__ via define
- src/bootstrap.ts: routes client-mode.json parsing through the
  selected mode
- .gitignore: ignore the per-deployment .nitro-build.json
- README: full usage and override section
- public/configuration assets regenerated by the updated prebuild flow

The renderer side (@nitrots/utils JsonParser) is updated in the
companion Nitro_Render_V3 commit on the dev branch.
This commit is contained in:
medievalshell
2026-05-18 20:38:26 +02:00
parent b2318b9e7c
commit 2fded7bc79
8 changed files with 276 additions and 22 deletions
+65
View File
@@ -31,6 +31,71 @@
- `yarn build` <== the final step to build the DIST folder this is where your browser needs to point / or upload this to your /client if you do the compile on a other machine (preferd)
- You can override any variable by passing it to `NitroConfig` in the index.html
## JSON / JSON5 configuration mode
Starting with this version of Nitro V3, you can choose how the client parses the
configuration files (`renderer-config.json`, `ui-config.json`, `client-mode.json`,
and the gamedata JSONs served by the renderer):
- **JSON5** (recommended) — accepts comments, trailing commas, single quotes
and unquoted identifiers. Easier to maintain, especially in `ui-config.json`
where you may want inline notes.
- **JSON (legacy strict)** — only valid standard JSON is accepted. Any comment
or trailing comma will fail the load with a clear error.
### Picking a mode
The first time you run `yarn start` or `yarn build`, an interactive prompt asks
which mode to use:
```
════════════════════════════════════════════════════════════
Nitro V3 — JSON mode configuration
════════════════════════════════════════════════════════════
1) JSON5 (recommended)
2) JSON (legacy strict)
Scelta [1=JSON5]:
```
Your choice is stored in `.nitro-build.json` at the project root (gitignored, so
each deployment keeps its own setting). Subsequent builds reuse it silently.
### Changing the mode later
Run the prompt again at any time:
```
yarn configure
```
You can also set the mode without interaction (useful in CI / scripts):
```
# one-shot override for a single build
NITRO_JSON_MODE=legacy yarn build
NITRO_JSON_MODE=json5 yarn build
# write the choice persistently
echo '{"jsonMode":"legacy"}' > .nitro-build.json
```
The recognized values are `legacy`, `json5`, and `auto` (auto = try strict JSON
first, fall back to JSON5 — equivalent to the original Render V3 behaviour).
### How it propagates
The chosen mode is injected at build time as the compile-time constant
`__NITRO_JSON_MODE__`. It is honoured by:
- `src/bootstrap.ts` when loading `client-mode.json`
- `@nitrots/utils``JsonParser.ts` in Render V3, used for every config file
and every gamedata JSON loaded by the renderer
In `legacy` mode, an invalid file produces a clear error that suggests switching
to JSON5; nothing is silently coerced.
## Usage
- To use Nitro you need `.nitro` assets generated, see [nitro-converter](https://git.krews.org/nitro/nitro-converter) for instructions