From 6616602417ba83642cbc06f1d3df3590570bc9bf Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Mon, 18 Sep 2023 08:25:51 -0500 Subject: [PATCH] revert changes from denoland/manual#689 (#116) --- runtime/manual/node/npm_specifiers.md | 137 ++++++++++++-------------- 1 file changed, 64 insertions(+), 73 deletions(-) diff --git a/runtime/manual/node/npm_specifiers.md b/runtime/manual/node/npm_specifiers.md index 75960460b..8f2d770ff 100644 --- a/runtime/manual/node/npm_specifiers.md +++ b/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:[@][/] ``` -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 -/// +```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:[@][/] ``` For example: ```sh -$ deno run --allow-read npm:cowsay@1.5.0 Hello there! +$ deno run --allow-env --allow-read npm:cowsay@1.5.0 Hello there! ______________ < Hello there! > -------------- @@ -108,7 +66,7 @@ $ deno run --allow-read npm:cowsay@1.5.0 Hello there! ||----w | || || -$ deno run --allow-read npm:cowsay@1.5.0/cowthink What to eat? +$ deno run --allow-env --allow-read npm:cowsay@1.5.0/cowthink What to eat? ______________ ( What to eat? ) -------------- @@ -119,9 +77,42 @@ $ deno run --allow-read npm:cowsay@1.5.0/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 +/// +``` + +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