Skip to content

docs: clarify first project run steps#3173

Merged
bartlomieju merged 8 commits into
mainfrom
worktree-agent-ae03f22321b77ddba
May 28, 2026
Merged

docs: clarify first project run steps#3173
bartlomieju merged 8 commits into
mainfrom
worktree-agent-ae03f22321b77ddba

Conversation

@bartlomieju

Copy link
Copy Markdown
Member

This tightens up runtime/getting_started/first_project.md so that a reader
following along from a clean shell can actually run the freshly initialized
project without hitting a confusing error.

Previously the page ran deno init my_project and then jumped straight to
deno main.ts, which fails from the parent directory because main.ts
lives inside my_project/. An explicit cd my_project step is now shown
between init and run so the example works end to end.

The page also explained the main.ts contents 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.ts contains without
anchoring 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.ts works
without an explicit run subcommand. A single sentence has been added
next to the first example noting that Deno infers run when given a file
path, which should head off the "is this a typo?" reaction from newcomers.

The brittle deno test output 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 init template
changes rarely enough that the drift risk is low. Happy to soften it in
a follow-up if reviewers disagree.

Ran deno fmt on the file after editing.

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 fibibot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. deno main.ts drops the network permission needed by the generated HTTP server. The current Deno 2.8.1 deno init template prints deno run --allow-net main.ts; without --allow-net, Deno.serve(handler) cannot bind without prompting/failing in non-interactive runs. Use deno run --allow-net main.ts here, 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.
@bartlomieju bartlomieju merged commit b542df7 into main May 28, 2026
2 checks passed
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.

2 participants