docs: clarify first project run steps#3173
Merged
Merged
Conversation
Add a `cd my_project` step before running the program, briefly note that Deno infers the `run` subcommand from a file path, and rephrase the `main.ts` description so it isn't pinned to a specific Deno version.
fibibot
requested changes
May 27, 2026
fibibot
left a comment
Contributor
There was a problem hiding this comment.
deno main.tsdrops the network permission needed by the generated HTTP server. The current Deno 2.8.1deno inittemplate printsdeno run --allow-net main.ts; without--allow-net,Deno.serve(handler)cannot bind without prompting/failing in non-interactive runs. Usedeno run --allow-net main.tshere, and keep the shorthand explanation only if it also mentions permissions.
Replace the two-paragraph opener (filler about Deno's tools, then the JS/TS note) with a single sentence previewing what the page covers, keeping the JS escape hatch. Also drops a stray em-dash later in the page.
The tree above already names the three files; restating them in prose adds nothing. Keep just the substance: what deno.json is for, and the shape of main.ts and main_test.ts.
The reader hasn't read main.ts at this point, so notes about the import.meta.main guard and the test importing the handler directly are detail without context. Trim to a one-line summary of what each file is for.
- Add a one-line note explaining the -N flag and linking to security,
so a first-project reader doesn't hit it cold.
- Drop the run-subcommand inference paragraph; the -N example obscures
the point it was making.
- Collapse the test-runner intro from three sentences to one.
- Rewrite the closing CTAs ('You're set' and 'To go deeper') with
tighter copy and a non-'here' link anchor.
The examples link directly above already serves the 'where next' job; TypeScript was a holdover from the original page's JS/TS framing and now reads as a random pick.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This tightens up
runtime/getting_started/first_project.mdso that a readerfollowing along from a clean shell can actually run the freshly initialized
project without hitting a confusing error.
Previously the page ran
deno init my_projectand then jumped straight todeno main.ts, which fails from the parent directory becausemain.tslives inside
my_project/. An explicitcd my_projectstep is now shownbetween init and run so the example works end to end.
The page also explained the
main.tscontents with an "As of Deno 2.8…"preamble, which silently goes stale every time a new release ships. The
sentence has been rephrased to describe what
main.tscontains withoutanchoring to a particular version, so the doc doesn't need a yearly bump.
While reading the run section it wasn't obvious why
deno main.tsworkswithout an explicit
runsubcommand. A single sentence has been addednext to the first example noting that Deno infers
runwhen given a filepath, which should head off the "is this a typo?" reaction from newcomers.
The brittle
deno testoutput block listing specific test names("handler returns hello", etc.) was considered but left as-is: the
specific names still carry real pedagogical value by showing readers
what's being tested against the handler, and the
deno inittemplatechanges rarely enough that the drift risk is low. Happy to soften it in
a follow-up if reviewers disagree.
Ran
deno fmton the file after editing.