revert changes from denoland/manual#689 (denoland#116)

runtime/manual/node/npm_specifiers.md

@@ -1,104 +1,62 @@
 # `npm:` specifiers
 
 Since version 1.28, Deno has native support for importing npm packages. This is
-done by importing using `npm:` specifiers. For example the following code:
+done by importing using `npm:` specifiers.
 
-```ts
-import { emojify } from "npm:node-emoji@2";
-
-console.log(emojify(":t-rex: :heart: NPM"));
-```
+The way these work is best described with an example that you can run with
+`deno run --allow-env`:
 
-Can be run with:
+```ts, ignore
+import chalk from "npm:chalk@5";
 
-```sh
-$ deno run main.js
-🦖 ❤️ NPM
+console.log(chalk.green("Hello!"));
 ```
 
-When doing this, no `npm install` is necessary and no `node_modules` folder is
-created. These packages are also subject to the same
-[permissions](../basics/permissions.md) as other code in Deno.
-
-npm specifiers have the following format:
+These npm specifiers have the following format:
 
-```
+```ts, ignore
 npm:<package-name>[@<version-requirement>][/<sub-path>]
 ```
 
-Several examples using popular npm modules can be found in our
-[tutorials](/runtime/tutorials) section.
-
-## TypeScript types
-
-Many packages ship with types, which will be available to Deno's TypeScript
-compiler without configuration.
-
-```ts
-import chalk from "npm:chalk@5";
-```
-
-Some packages do not include types. However, you can specify their types with a
-[`@deno-types`](../advanced/typescript/types.md) directive. For example, using a
-[`@types`](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html#definitelytyped--types)
-package:
+Another example with express:
 
-```ts
-// @deno-types="npm:@types/express@^4.17"
+```js, ignore
+// main.js
 import express from "npm:express@^4.17";
-```
-
-### Module resolution
-
-The official TypeScript compiler `tsc` supports different
-[moduleResolution](https://www.typescriptlang.org/tsconfig#moduleResolution)
-settings. Deno only supports the modern `node16` resolution. Unfortunately many
-NPM packages fail to correctly provide types under node16 module resolution,
-which can result in `deno check` reporting type errors that `tsc` does not
-report.
+const app = express();
 
-If a default export from an `npm:` import appears to have a wrong type (with the
-right type seemingly being available under the `.default` property), it's most
-likely that the package provides incorrect types under node16 module resolution
-for imports from ESM. You can verify this by checking if the error also occurs
-with `tsc --module node16` and `"type": "module"` in `package.json` or by
-consulting the [Are the types wrong?](https://arethetypeswrong.github.io/)
-website (particularly the "node16 from ESM" row).
+app.get("/", (req, res) => {
+  res.send("Hello World");
+});
 
-If you want to use a package that doesn't support TypeScript's node16 module
-resolution, you can:
-
-1. Use a [CDN](./cdns.md), that rebuilds the packages for Deno support, rather
-   than using an `npm:` specifier.
-2. Ignore type errors with`// @ts-expect-error` or `// @ts-ignore`.
-
-### Including Node types
+app.listen(3000);
+console.log("listening on http://localhost:3000/");
+```
 
-Node ships with many built-in types like `Buffer` that might be referenced in an
-npm package's types. To load these, you must add a types reference directive to
-the `@types/node` package:
+Then doing the following will start a simple express server:
 
-```ts
-/// <reference types="npm:@types/node" />
+```sh
+$ deno run -A main.js
+listening on http://localhost:3000/
 ```
 
-Note that it is fine to not specify a version for this in most cases because
-Deno will try to keep it in sync with its internal Node code, but you can always
-override the version used if necessary.
+When doing this, no `npm install` is necessary and no `node_modules` folder is
+created. These packages are also subject to the same permissions as Deno
+applications.
 
 ## npm executable scripts
 
 npm packages with `bin` entries can be executed from the command line without an
 `npm install` using a specifier in the following format:
 
-```
+```ts, ignore
 npm:<package-name>[@<version-requirement>][/<binary-name>]
 ```
 
 For example:
 
 ```sh
-$ deno run --allow-read npm:[email protected] Hello there!
+$ deno run --allow-env --allow-read npm:[email protected] Hello there!
  ______________
 < Hello there! >
  --------------
@@ -108,7 +66,7 @@ $ deno run --allow-read npm:[email protected] Hello there!
                 ||----w |
                 ||     ||
 
-$ deno run --allow-read npm:[email protected]/cowthink What to eat?
+$ deno run --allow-env --allow-read npm:[email protected]/cowthink What to eat?
  ______________
 ( What to eat? )
  --------------
@@ -119,9 +77,42 @@ $ deno run --allow-read npm:[email protected]/cowthink What to eat?
                 ||     ||
 ```
 
+## TypeScript types
+
+Many packages ship with types out of the box, you can import those and use them
+with types easily:
+
+```ts, ignore
+import chalk from "npm:chalk@5";
+```
+
+Some packages do not though, but you can specify their types with a
+[`@deno-types`](../advanced/typescript/types.md) directive. For example, using a
+[`@types`](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html#definitelytyped--types)
+package:
+
+```ts, ignore
+// @deno-types="npm:@types/express@^4.17"
+import express from "npm:express@^4.17";
+```
+
+### Including Node types
+
+Node ships with many built-in types like `Buffer` that might be referenced in an
+npm package's types. To load these you must add a types reference directive to
+the `@types/node` package:
+
+```ts, ignore
+/// <reference types="npm:@types/node" />
+```
+
+Note that it is fine to not specify a version for this in most cases because
+Deno will try to keep it in sync with its internal Node code, but you can always
+override the version used if necessary.
+
 ## `--node-modules-dir` flag
 
-`npm:` specifiers resolve npm packages to a central global npm cache. This works
+npm specifiers resolve npm packages to a central global npm cache. This works
 well in most cases and is ideal since it uses less space and doesn't require a
 node_modules directory. That said, you may find cases where an npm package
 expects itself to be executing from a `node_modules` directory. To improve
@@ -145,9 +136,9 @@ deno run --node-modules-dir main.ts
 ...will create a `node_modules` folder in the current directory with a similar
 folder structure to npm.
 
-![screenshot of generated node_modules folder](../images/node_modules_dir.png)
+![](../images/node_modules_dir.png)
 
-Note that this is all done automatically when calling `deno run` and there is no
+Note that this is all done automatically when calling deno run and there is no
 separate install command necessary.
 
 Alternatively, if you wish to disable the creation of a `node_modules` directory