docs: name the dev server port flag in getting started - #3603
Conversation
Port 3000 is the most contended port on a developer machine, and the getting-started pages tell the reader to run a bare `veryfront dev` and then open port 3000. `veryfront dev` no longer hard-fails when 3000 is taken (#3562): it scans forward for the first free port and announces the switch. Neither half reaches a doc-only reader. `--port` is documented only in `veryfront dev --help`, and nothing on either page explains why the server came up on 3001, so the reader opens the 3000 the page printed and reaches whatever process took it. Document the flag and the fallback on both pages that start the dev server, and pin them with a contract test that reads the `--port` declaration out of `cli/commands/dev/command-help.ts`, so removing or renaming the flag fails the docs.
|
Warning Review limit reached
Next review available in: 39 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e5ab4ae59b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
`scripts/lint/audit-cwd-relative-test-reads.ts` failed the new case: it read `cli/commands/dev/command-help.ts` and the two getting-started pages through the process cwd, and test files share one process under `--parallel`, so a sibling isolate holding `withCwd` resolves those reads somewhere else. Resolve all three from `import.meta.url` instead, which drops the file back to its baseline of 29 callback-scope cwd reads.
Review caught that "Verify it worked" hard-codes 3000 immediately after the new paragraph explaining the port can be 3001 or 4000. A reader who took either path would open or curl the port they were just told they are not on. Point both steps at the port `veryfront dev` printed.
The published copy of this page is linted by veryfront-docs' `scripts/check-code-docs-quality.mjs`, which rejects em dashes in public docs. Rewrite the sentence the previous commit added without them, so the synced file passes there too.
1 participant
Symptom
Round-2 verification finding [7], doc half. Against published
0.1.1229, with127.0.0.1:3000held by another process:The CLI half of that finding is fixed and shipped (#3562): no hard fail, no
[initialization-error], the server binds 3001 and the dev MCP server moves to3003. The doc half is not. Neither getting-started page mentions
--port, andneither warns the reader that the printed port can differ from the one in the
page's own examples. A reader whose 3000 is busy follows the page to
http://localhost:3000and reaches whatever process took it.--portis documented only inveryfront dev --help.Why the earlier fix did not cover this
#3562 changed CLI behaviour only. Its own commit message named the doc gap
("the getting-started docs ... never mention
--port") as the motivation, butthe change never touched
docs/. Nothing regressed; the doc half was simplynever in scope.
Change
docs/getting-started/create-project.md: a### Change the portsubsectionunder "Run the dev server" with the
--portflag, the fallback behaviour, andthe notice line the CLI actually prints.
docs/getting-started/quickstart.md: the same facts in one paragraph plus a--portexample, ahead of the existing dev-MCP paragraph (whose "app portplus 2" is relative to the port the server bound, which the new paragraph now
makes visible).
tests/docs/guide-content.test.ts: a contract test that reads the--portdeclaration out of
cli/commands/dev/command-help.tsand requires both pagesto name the flag and the fallback notice.
No source behaviour changes.
Verification
Repro built against the published artifact, in a sandbox outside the platform
checkout:
npm install veryfront@0.1.1229,veryfront init test-app --template minimal, blocker on127.0.0.1:3000, thenveryfront dev. Output above;lsofconfirmed127.0.0.1:3001and[::1]:3003.veryfront dev --port 4000binds 4000 with MCP on 4002. Every documented string is copied from that run.
Test is red before the doc change (
docs/getting-started/create-project.mddoesnot contain "veryfront dev --port") and green after:
Live URLs that must show this
This repo's
docs/is not whatveryfront.comserves. The published copy isveryfront-docs/docs/code/**, which has drifted from this tree, so the samechange goes there in a companion PR. The pages to check after both land:
Both must contain the string
veryfront dev --port. Today they contain "port"zero times in rendered text.