Unexpected errors and warnings when running json-server --watch

I'm trying to use json-server as follows:

$ json-server --watch db.json

However, I'm getting errors or warnings when I run that command, depending on the version I have installed:

1.0.0-alpha.1-1.0.0-alpha.12:

sh: json-server: command not found

or (on Windows):

The term 'json-server' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
At line:1 char:1
+ json-server --watch db.json

or (if executed via npx):

npm ERR! could not determine executable to run

1.0.0-alpha.13:

node:internal/errors:496
    ErrorCaptureStackTrace(err);
    ^

TypeError [ERR_PARSE_ARGS_UNKNOWN_OPTION]: Unknown option '--watch'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- "--watch"

1.0.0-alpha.14+:

--watch/-w can be omitted, JSON Server 1+ watches for file changes by default

1.0.0-alpha.13+, if using Node.js before v18.3.0, v16.17.0:

import { parseArgs } from 'node:util';
         ^^^^^^^^^
SyntaxError: The requested module 'node:util' does not provide an export named 'parseArgs'

Minimal package file (update version of json-server as needed):

{
  "name": "q77787616",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "json-server --watch db.json"
  },
  "keywords": [],
  "license": "ISC",
  "dependencies": {
    "json-server": "1.0.0-alpha.12"
  }
}

Solution

json-server is currently in active development towards v1, but unfortunately these alpha versions are being published to npm with the latest tag, so are being installed in favour of the stable version (currently 0.17.4) if you simply npm install json-server. This has caused various issues:

Prior to alpha.13 the correct binary wasn't installed at all, so the json-server command couldn't be found (typicode/json-server#1472).
With alpha.13 the binary was included, but the CLI changed such that --watch was an invalid argument (typicode/json-server#1474):
```
$ npx json-server@1.0.0-alpha.13 --help
Usage: json-server [options] <file>
Options:
  -p, --port <port>  Port (default: 3000)
  -h, --host <host>  Host (default: localhost)
  -s, --static <dir> Static files directory (multiple allowed)
  --help  Show this message
```
- The argument parsing is provided by parseArgs from node:util, which was introduced in Node.js v16.17 and v18.3, so earlier versions aren't supported.
From alpha.14 onwards, --watch is supported but unnecessary, so the message was reduced to a warning.

You can check which version you currently have installed with:

npm ls json-server

Given the active development and alpha status, the best thing to do currently is to explicitly install the stable version (the documentation for this is still available here):

$ npm install json-server@0

Alternatively, if you want to use the alpha v1 and are using an appropriate Node.js version (i.e. ^16.17 || >=18.3), you can npm install json-server@latest to get the latest version (ensure you have at least alpha.14) and use the command without the --watch flag:

$ json-server db.json