Skip to content

docs(node): make quickstart runnable end to end - #394

Closed
JoshKappler wants to merge 1 commit into
mainfrom
docs-node-quickstart
Closed

docs(node): make quickstart runnable end to end#394
JoshKappler wants to merge 1 commit into
mainfrom
docs-node-quickstart

Conversation

@JoshKappler

Copy link
Copy Markdown
Contributor

Type: fix. The Node quickstart cannot be completed as written. A reader who follows it top to bottom hits a hard error on the first code sample and never reaches a running service.

This quickstart was created in the #354 docs refactor merged July 16 and had not been walked end to end yet. The docs bots do mechanical sync and grammar passes (open PR #390 is a grammar-only pass on a sibling quickstart page), so first-run defects like this survive them.

What is broken

Following the page's own steps produces a project whose package.json has "type": "commonjs", which is what npm init -y writes on current npm. The first sample uses ESM import syntax, so node server.js fails immediately:

SyntaxError: Cannot use import statement outside a module

Three more gaps stop the page short of a running service:

  • The intro names Express as the target use case and the samples import express, but the install step only installs gt-node and gt.
  • No block has an app.listen, and no step runs or checks the server, so even with the imports fixed node server.js exits silently.
  • npx gt translate dead-ends: it requires a gt.config.json and credentials that the page never creates, and it points at gt init, which the page never mentions.

What this changes

  • Adds a one-line note in step 1 to set "type": "module".
  • Adds express to the install commands in all four package managers.
  • Adds app.listen to the final server block and a new "Run and verify" step (node server.js plus a curl and the expected response).
  • Adds a one-line note at the translate step to run npx gt init first to create gt.config.json and credentials.
  • Fixes the code fences that were tagged ts while titled server.js; the code is plain JavaScript.

Verified by scaffolding the page from scratch in a clean directory: npm init -y, set "type": "module", install the dependencies, paste the assembled server code, node server.js, then curl. The server returns HTTP 200 with {"message":"Hello, Alice!"} (the source string, since no credentials are set). The repo CI checks pass locally: unsafe-HTML validation, link validation, and pnpm build:content.

On the obvious counterargument

Node's error message does name the fix for the ESM problem, so an experienced reader could add "type": "module" on their own. That holds for that one line and not for the rest: the missing express install, the missing app.listen, and the gt translate prerequisites give no such hint, and a quickstart should not make the reader debug its first sample. The page still states the ESM line so the happy path runs with no detours.

Coordination with #389

Draft PR #389 is editing this same file's step 2 (credentials and environment variables), blocked on a gt-node release. I kept my scope to page structure and left step 2 untouched. One consequence: the step 2 code block keeps its ts fence, so after this lands the page has one ts-fenced block and two js-fenced blocks. Aligning that last fence belongs with #389's rewrite of that block, so I note it here rather than editing a region #389 is actively changing.

There is also a merge-order interaction. This PR's new "Run and verify" step expects the handler to echo the source string, which is correct on current main where step 2 sets no API key. #389 rewrites step 2 to export a real dev key, and a dev key can trigger on-demand runtime translation instead of a source-string echo, which would make the verify step's expected output wrong. Two clean orders: land #389 first, then a one-line follow-up here adjusting the verify wording; or land this PR first (correct on current main) and make that same one-line adjustment when #389 lands. Either way it is a single follow-up line, not a rebase conflict.

If I have the framing wrong

If the quickstart intentionally assumes the reader already has an Express app and a configured project, I'm happy to rescope to that framing instead, for example dropping the install and run steps and stating the assumption up front.

@JoshKappler

Copy link
Copy Markdown
Contributor Author

Folding this into #391 so the quickstart fixes are one review instead of four. The commit is cherry-picked there unchanged and the write-up moved into that PR's body. The #389 coordination note rides along in #391.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant