When suggesting `--port` in Getting started, clarify that `npm run` needs `--` to pass additional arguments about framework

[Fil]

@anacierdem can you give some context, like what operating system you were running? We haven't been able to reproduce an EACCES error on unprivileged ports.

[mbostock]

The preview server does indeed check whether the port is available here:

framework/src/preview.ts

Lines 80 to 89 in d244fa1

	for (port = 3000; true; ++port) {
	try {
	await new Promise<void>((resolve, reject) => {
	server.once("error", reject);
	server.listen(port, hostname, resolve);
	});
	break;
	} catch (error) {
	if (!isSystemError(error) || error.code !== "EADDRINUSE") throw error;
	}

However, it’s looking for a EADDRINUSE error. The EACCESS error suggests a different issue, which is that the process doesn’t have permission to open this port. That is surprising, since normally ports >1024 are allowed to be used without needing sudo privileges. Perhaps Framework should treat both EACCESS and EADDRINUSE errors the same way?

The docs are correct here in suggesting --port 3001, they just fail to document npm run’s behavior and need for --, which is documented here:

https://docs.npmjs.com/cli/v10/commands/npm-run-script

Generally, we don’t try to duplicate the documentation of other tools in our docs because there’s too much to cover. But we could add a note about needing the -- here.