From 0334a37b911e1c57767762953733480e40ab4949 Mon Sep 17 00:00:00 2001 From: Jo Franchetti Date: Mon, 2 Sep 2024 11:59:14 +0200 Subject: [PATCH 01/16] docs: move modules page over --- runtime/fundamentals/modules.md | 480 ++++++++++++++++++ .../manual/advanced/continuous_integration.md | 6 +- runtime/manual/advanced/http_imports.md | 38 -- runtime/manual/basics/modules/index.md | 241 --------- .../basics/modules/integrity_checking.md | 123 ----- runtime/manual/basics/modules/proxies.md | 11 - .../basics/modules/publishing_modules.md | 76 --- .../basics/modules/reloading_modules.md | 24 - 8 files changed, 483 insertions(+), 516 deletions(-) create mode 100644 runtime/fundamentals/modules.md delete mode 100644 runtime/manual/advanced/http_imports.md delete mode 100644 runtime/manual/basics/modules/index.md delete mode 100644 runtime/manual/basics/modules/integrity_checking.md delete mode 100644 runtime/manual/basics/modules/proxies.md delete mode 100644 runtime/manual/basics/modules/publishing_modules.md delete mode 100644 runtime/manual/basics/modules/reloading_modules.md diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md new file mode 100644 index 000000000..d49799f76 --- /dev/null +++ b/runtime/fundamentals/modules.md @@ -0,0 +1,480 @@ +--- +title: "Using modules in Deno" +oldUrl: + - /runtime/manual/basics/modules/ + - /runtime/manual/basics/modules/integrity_checking/ + - /runtime/manual/basics/modules/module_metadata/ + - /runtime/manual/basics/modules/proxies/ + - /runtime/manual/basics/modules/publishing_modules/ + - /runtime/manual/basics/modules/reloading_modules/ + - /runtime/manual/advanced/publishing/dnt/ + - /runtime/manual/advanced/publishing/ + - /runtime/manual/basics/vendoring/ + - /runtime/manual/node/cdns.md + - /runtime/manual/advanced/http_imports/ +--- + +Deno uses +[ECMAScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) +exclusively. + +Since 2015, ES Modules have been an integral part of the JavaScript +specification, enabling seamless module usage directly in the browser. Unlike +CommonJS, which is not natively supported in browsers, ES Modules provide a +standardized way to manage dependencies and modularize code. Deno aims to narrow +the gap between browser and server environments by fully embracing ES Modules, +ensuring a more consistent and streamlined development experience across both +platforms. + +## Importing modules + +In this example the `add` function is imported from a local `calc.ts` module. + +```ts title="calc.ts" +export function add(a: number, b: number): number { + return a + b; +} +``` + +```ts title="main.ts" +import { add } from "./calc.ts"; + +console.log(add(1, 2)); // 3 +``` + +You can run this example by calling `deno run main.ts` in the directory that +contains `main.ts` and `calc.ts`. + +## Adding third party modules and libraries to deno.json + +Using remote modules (downloaded from a registry) in Deno uses the same `import` +syntax as your local code. + +The modules that you add to your project are tracked as `imports` in +`deno.json` - we call this the import map. + +```json title="deno.json" +{ + "imports": { + "@scopename/mypackage": "jsr:@scopename/mypackage@^16.1.0" + } +} +``` + +You can add modules using the `deno add` subcommand: + +```sh +# Add the latest version of the module to deno.json +$ deno add @luca/cases +Add @luca/cases - jsr:@luca/cases@^1.0.0 +``` + +```json title="deno.json" +{ + "imports": { + "@luca/cases": "jsr:@luca/cases@^1.0.0" + } +} +``` + +The `deno add` command will automatically add the latest version of the module +you requested to your project imports, unless you specify an exact version: + +```sh +# Passing an exact version +$ deno add @luca/cases@1.0.0 +Add @luca/cases - jsr:@luca/cases@^1.0.0 +``` + +## Local imports + +When importing local modules, use relative paths that start with `./` or `../` +and include the full file extension. This means you need to specify `.ts`, +`.js`, `.tsx`, `.jsx`, or `.mjs` extensions explicitly. This ensures that Deno +correctly resolves the module location relative to the current file. For +example: + +```ts +// Always include the file extension +import { add } from "./calc.ts"; +``` + +## Using installed modules + +Once a package is added to the import map in `deno.json`, you can import the +module by its name, and Deno will automatically resolve the module. For example: + +```ts title="main.ts" +import { camelCase } from "@luca/cases"; + +camelCase("hello world"); // "helloWorld" +``` + +## Package Registries + +Deno recommends that you use [JSR](https://jsr.io/), the JavaScript registry, to +publish and manage your modules for the best publishing experience. JSR offers +automatic documentation generation, semver resolution and improved performance +for TypeScript code. Deno also supports +[other platforms](https://jsr.io/docs/other-registries) for publishing modules, +such as npm, and JavaScript CDNs like deno.land/x, esm.h and unpkg.com + +By default when you use the CLI, the package will be resolved from JSR. + +```bash +deno add @scopename/mypackage +``` + +The resulting import map contains the `jsr:` import specifier in the resulting +`deno.json` file. + +```json +{ + "imports": { + "@scopename/mypackage": "jsr:@scopename/mypackage@^16.1.0" + } +} +``` + +Deno supports the following registries: + +| Registry | Specifier | +| -------- | --------- | +| JSR | jsr: | +| npm | npm: | + +To import a package from `npm` you need to prefix the package name with the +`npm:` specifier: + +```bash +$ deno add npm:uuid +Add uuid - npm:uuid@^10.0.0 +``` + +The resulting `deno.json` will contain the following import: + +```json +{ + "imports": { + "uuid": "npm:uuid@^10.0.0" + } +} +``` + +You can then use the npm module by importing it by name from the import map. + +```ts title="mod.ts" +import * as uuid from "uuid"; + +console.log(uuid.v4()); +``` + +## Importing modules from HTTP URLs + +Deno supports importing modules from HTTP URLs. Note that npm packages can be +directly imported via the [`npm:` specifier](TODO:specifiers-link). + +```typescript +import { render } from "https://esm.sh/preact"; +``` + +You can also import modules from a URL by adding it to your `deno.json` import +map: + +```json title="deno.json" +{ + "imports": { + "preact": "https://esm.sh/preact" + } +} +``` + +URL imports should be used with caution, as they can introduce security risks. +When importing modules from a URL, you are trusting the server to serve the +correct code. If the server is compromised, it could serve malicious code to +your application. For this reason, it is recommended to **use URL imports only +from trusted sources**. They can also cause versioning issues if you import +different versions in different files. + +## Package Versions + +It is possible to specify a version range for the package you are importing. +This is done using the `@` symbol followed by a version range specifier, and +follows the [semver](https://semver.org/) versioning scheme. + +For example: + +```bash +@scopename/mypackage # latest version +@scopename/mypackage@16.1.0 # exact version +@scopename/mypackage@^16.1.0 # latest patch version 16.x +@scopename/mypackage@~16.1.0 # latest version that doesn't increment the first non-zero portion +``` + +### Import symbols + +| Symbol | Description | Example | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `1.2.3` | An exact version. Only this specific version will be used. | `1.2.3` | +| `^1.2.3` | Compatible with version 1.2.3. Allows updates that do not change the leftmost non-zero digit.
For example, `1.2.4` and `1.3.0` are allowed, but `2.0.0` is not. | `^1.2.3` | +| `~1.2.3` | Approximately equivalent to version 1.2.3. Allows updates to the patch version.
For example, `1.2.4` is allowed, but `1.3.0` is not. | `~1.2.3` | +| `>=1.2.3` | Greater than or equal to version 1.2.3. Any version `1.2.3` or higher is allowed. | `>=1.2.3` | +| `<=1.2.3` | Less than or equal to version 1.2.3. Any version `1.2.3` or lower is allowed. | `<=1.2.3` | +| `>1.2.3` | Greater than version 1.2.3. Only versions higher than `1.2.3` are allowed. | `>1.2.3` | +| `<1.2.3` | Less than version 1.2.3. Only versions lower than `1.2.3` are allowed. | `<1.2.3` | +| `1.2.x` | Any patch version within the minor version 1.2. For example, `1.2.0`, `1.2.1`, etc. | `1.2.x` | +| `1.x` | Any minor and patch version within the major version 1. For example, `1.0.0`, `1.1.0`, `1.2.0`, etc. | `1.x` | +| `*` | Any version is allowed. | `*` | + +## Importing by URL + +Deno also supports import statements that reference URLs, either directly: + +```js +import { Application } from "https://deno.land/x/oak/mod.ts"; +``` + +or part of your `deno.json` import map: + +```json +{ + "imports": { + "oak": "https://deno.land/x/oak/mod.ts" + } +} +``` + +Supporting URL imports enables us to support the following JavaScript CDNs, as +they provide URL access to JavaScript modules: + +- [deno.land/x](https://deno.land/x) +- [esm.sh](https://esm.sh) +- [unpkg.com](https://unpkg.com) + +URL imports are useful if you have a small, often single file, Deno project that +doesn't require any other configuration because you can avoid having a +`Deno.json` file at all. It's not advised to use this style of import in larger +applications as you may end up with version conflicts (where different files use +different version specifiers). + +From a security perspective, the contents of files at URLs can change, so we do +not generally recommend this approach for third-party components. + +URL imports remain supported, **but we recommend using a package registry for +the best experience.** + +### Overriding URL imports + +The other situation where import maps can be very useful is to override URL +imports in specific modules. + +Let's say you want to override a `https://deno.land/x/my-library@1.0.0/mod.ts` +specifier that is used inside files coming from `https://deno.land/x/example/` +to a local patched version. You can do this by using a scope in the import map +that looks something like this: + +```json +{ + "imports": { + "example/": "https://deno.land/x/example/" + }, + "scopes": { + "https://deno.land/x/example/": { + "https://deno.land/x/my-library@1.0.0/mod.ts": "./patched/mod.ts" + } + } +} +``` + +:::note + +URL imports have no notion of packages. Only the import map at the root of your +project is used. Import maps used inside URL dependencies are ignored. + +::: + +## Proxies + +Deno is able to handle network requests through a proxy server, useful for +various reasons such as security, caching, or accessing resources behind a +firewall. The runtime supports supports proxies for module downloads and the Web +standard `fetch` API. + +Deno reads proxy configuration from environment variables: `HTTP_PROXY`, +`HTTPS_PROXY` and `NO_PROXY`. + +In case of Windows, if environment variables are not found, Deno falls back to +reading proxies from the registry. + +## Publishing modules + +Any Deno program that defines an export can be published as a module. This +allows other developers to import and use your code in their own projects. +Modules can be published to [JSR](https://jsr.io), the modern JavaScript and +TypeScript registry. Check out the +[JSR documentation on publishing modules](https://jsr.io/docs/publishing-packages) +for more information. + +## Publishing for Node.js + +You can make your Deno modules available to Node.js users with the +[dnt](https://github.com/denoland/dnt) build tool. + +dnt allows you to develop your Deno module mostly as-is and use a single Deno +script to build, type check, and test an npm package in an output directory. +Once built, you only need to `npm publish` the output directory to distribute it +to Node.js users. + +For more details, see +[https://github.com/denoland/dnt](https://github.com/denoland/dnt). + +## Reloading modules + +By default, Deno uses a global cache directory (`DENO_DIR`) for downloaded +dependencies. This cache is shared across all projects. + +You can force deno to refetch and recompile modules into the cache using the +`--reload` flag of the `deno cache` or `deno run` subcommand. + +```bash +# Reload everything +deno cache --reload my_module. + +# Reload a specific module +deno cache --reload=jsr:@std/fs my_module.ts +``` + +## Vendoring + +If your project has external dependencies, you may want to store them locally to +avoid downloading them from the internet every time you build your project. This +is especially useful when building your project on a CI server or in a Docker +container, or patching or otherwise modifying the remote dependencies. + +Deno offers this functionality through a setting in your `deno.json` file: + +```json +{ + "vendor": true +} +``` + +Add the above snippet to your `deno.json` file and Deno will cache all +dependencies locally in a `vendor` directory when the project is run, or you can +optionally run the `deno cache` command to cache the dependencies immediately: + +```bash +deno cache main.ts +``` + +You can then run the application as usual with `deno run`: + +```bash +deno run main.ts +``` + +After vendoring, you can run `main.ts` without internet access by using the +`--cached-only` flag, which forces Deno to use only locally available modules. + +## Integrity Checking and Lock Files + +Imagine your module relies on a remote module located at https://some.url/a.ts. +When you compile your module for the first time, `a.ts` is fetched, compiled, +and cached. This cached version will be used until you either run your module on +a different machine (such as in a production environment) or manually reload the +cache (using a command like `deno cache --reload`). + +But what if the content at `https://some.url/a.ts` changes? This could result in +your production module running with different dependency code than your local +module. To prevent this, Deno uses integrity checking and lock files. + +Deno uses a `deno.lock` file to check external module integrity. To opt into a +lock file, either: + +1. Create a `deno.json` file in the current or an ancestor directory, which will + automatically create an additive lockfile at `deno.lock`. +2. Use the `--lock=deno.lock` flag to enable and specify lock file checking. To + update or create a lock use `--lock=deno.lock --lock-write`. The + `--lock=deno.lock` tells Deno what the lock file to use is, while the + `--lock-write` is used to output dependency hashes to the lock file + (`--lock-write` must be used in conjunction with `--lock`). + +A `deno.lock` might look like this, storing a hash of the file against the +dependency: + +```json +{ + "https://deno.land/std@0.224.0/textproto/mod.ts": "3118d7a42c03c242c5a49c2ad91c8396110e14acca1324e7aaefd31a999b71a4", + "https://deno.land/std@0.224.0/io/util.ts": "ae133d310a0fdcf298cea7bc09a599c49acb616d34e148e263bcb02976f80dee", + "https://deno.land/std@0.224.0/async/delay.ts": "35957d585a6e3dd87706858fb1d6b551cb278271b03f52c5a2cb70e65e00c26a", + ... +} +``` + +### Auto-generated lockfile + +As mentioned above, when a Deno configuration file is resolved (ex. `deno.json`) +then an additive lockfile will be automatically generated. By default, the path +of this lockfile will be `deno.lock`. You can change this path by updating your +`deno.json` to specify this: + +```jsonc +{ + "lock": "./lock.file" +} +``` + +Or disable automatically creating and validating a lockfile by specifying: + +```jsonc +{ + "lock": false +} +``` + +### Using `--lock` and `--lock-write` flags + +You may have a file that imports a dependency and looks something like this: + +```ts title="src/deps.ts" +export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts"; +``` + +To create a lock file, you can use the `--lock` and `--lock-write` flags: + +```shell +# Create/update the lock file "deno.lock". +deno cache --lock=deno.lock --lock-write src/deps.ts + +# Include it when committing to source control. +git add -u deno.lock +git commit -m "feat: Add support for xyz using xyz-lib" +git push +``` + +Collaborator on another machine -- in a freshly cloned project tree: + +```shell +# Download the project's dependencies into the machine's cache, integrity +# checking each resource. +deno cache --reload --lock=deno.lock src/deps.ts + +# Done! You can proceed safely. +deno test --allow-read src +``` + +### Runtime verification + +Like caching above, you can also use lock files during use of the `deno run` sub +command, validating the integrity of any locked modules during the run. Remember +that this only validates against dependencies previously added to the lock file. + +You can take this a step further as well by using the `--cached-only` flag to +require that remote dependencies are already cached. + +```shell +deno run --lock=deno.lock --cached-only mod.ts +``` + +This will fail if there are any dependencies in the dependency tree for mod.ts +which are not yet cached. diff --git a/runtime/manual/advanced/continuous_integration.md b/runtime/manual/advanced/continuous_integration.md index 0f566c50f..501f3587f 100644 --- a/runtime/manual/advanced/continuous_integration.md +++ b/runtime/manual/advanced/continuous_integration.md @@ -178,9 +178,9 @@ key: ${{ hashFiles('deno.lock') }} ``` To make this work you will also need a have a lockfile in your Deno project, -which is discussed in detail [here](../basics/modules/integrity_checking.md). -Now, if the contents of `deno.lock` are changed, a new cache will be made and -used in subsequent pipeline runs thereafter. +which is discussed in detail [here](TODO:integrity-checking-link). Now, if the +contents of `deno.lock` are changed, a new cache will be made and used in +subsequent pipeline runs thereafter. To demonstrate, let's say you have a project that uses the logger from [`@std/log`](https://jsr.io/@std/log): diff --git a/runtime/manual/advanced/http_imports.md b/runtime/manual/advanced/http_imports.md deleted file mode 100644 index 07dce7411..000000000 --- a/runtime/manual/advanced/http_imports.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Importing modules from HTTP URLs" -oldUrl: -- runtime/manual/node/cdns.md ---- - -Deno supports importing modules from HTTP URLs. This is useful for importing -modules from a CDN or from a server that serves JavaScript modules. Note that -npm packages can be directly imported via the -[`npm:` specifier](../../manual/node/npm_specifiers). - -```typescript -import { render } from "https://esm.sh/preact"; -``` - -You can also import modules from a URL by adding it to your `deno.json` import -map: - -```json -{ - "imports": { - "preact": "https://esm.sh/preact" - } -} -``` - -Supporting URL imports enables us to support the following JavaScript CDNs, as -they provide URL access to JavaScript modules: - -- [esm.sh](https://esm.sh/) (recommended) -- [jspm.io](https://jspm.io/) - -URL imports should be used with caution, as they can introduce security risks. -When importing modules from a URL, you are trusting the server to serve the -correct code. If the server is compromised, it could serve malicious code to -your application. For this reason, it is recommended to use URL imports only -from trusted sources. They can also cause versioning issues if you import -different versions in different files. diff --git a/runtime/manual/basics/modules/index.md b/runtime/manual/basics/modules/index.md deleted file mode 100644 index c17590ad5..000000000 --- a/runtime/manual/basics/modules/index.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: "ECMAScript Modules in Deno" -oldUrl: - - /runtime/fundamentals/esm.sh - - /runtime/manual/linking_to_external_code - - /runtime/manual/examples/manage_dependencies ---- - -Deno by default standardizes the way modules are imported in both JavaScript and -TypeScript using the -[ECMAScript module standard](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). -In line with this standard, **file names must be specified in full**. You should -not omit the file extension and there is no special handling of `index.js`. - -```ts -// Always include the file extension -import { add } from "./calc.ts"; -``` - -## Importing modules - -In this example the `add` function is imported from a local `calc.ts` module. - -```ts title="calc.ts" -export function add(a: number, b: number): number { - return a + b; -} -``` - -```ts title="main.ts" -import { add } from "./calc.ts"; - -console.log(add(1, 2)); // 3 -``` - -You can run this example by calling `deno run main.ts` in the directory that -contains `main.ts` and `calc.ts`. - -## Adding third party modules and libraries to deno.json - -Using remote modules (downloaded from a registry) in Deno uses the same `import` -syntax as your local code. - -The modules that you add to your project are tracked as `imports` in -`deno.json` - we call this the import map. - -```json title="deno.json" -{ - "imports": { - "@scopename/mypackage": "jsr:@scopename/mypackage@^16.1.0" - } -} -``` - -You can add modules using the `deno add` subcommand: - -```sh -# Add the latest version of the module to deno.json -$ deno add @luca/cases -Add @luca/cases - jsr:@luca/cases@^1.0.0 -``` - -```json title="deno.json" -{ - "imports": { - "@luca/cases": "jsr:@luca/cases@^1.0.0" - } -} -``` - -The `deno add` command will automatically add the latest version of the module -you requested to your project imports, unless you specify an exact version: - -```sh -# Passing an exact version -$ deno add @luca/cases@1.0.0 -Add @luca/cases - jsr:@luca/cases@^1.0.0 -``` - -## Using installed modules - -Once a package is added to the import map in `deno.json`, you can import the -module by its name, and Deno will automatically resolve the module. For example: - -```ts title="main.ts" -import { camelCase } from "@luca/cases"; - -camelCase("hello world"); // "helloWorld" -``` - -## Package Registries - -Deno recommends that you use [JSR](https://jsr.io/), the JavaScript registry, to -publish and manage your modules for the best publishing experience. JSR offers -automatic documentation generation, semver resolution and improved performance -for TypeScript code. Deno also supports -[other platforms](https://jsr.io/docs/other-registries) for publishing modules, -such as npm, and JavaScript CDNs like deno.land/x, esm.sh and unpkg.com - -By default when you use the CLI, the package will be resolved from JSR. - -```bash -deno add @scopename/mypackage -``` - -The resulting import map contains the `jsr:` import specifier in the resulting -`deno.json` file. - -```json -{ - "imports": { - "@scopename/mypackage": "jsr:@scopename/mypackage@^16.1.0" - } -} -``` - -## Importing from other package registries - -Using existing packages from registries like `npm` is equivalent to the -experience in `node`. To add a package from `npm` you need to prefix the package -name with the `npm:` specifier: - -```bash -$ deno add npm:uuid -Add uuid - npm:uuid@^10.0.0 -``` - -The resulting `deno.json` will look like this: - -```json -{ - "imports": { - "uuid": "npm:uuid@^10.0.0" - } -} -``` - -You will then be able to use the `npm` module by importing it with the name from -the import map. - -```ts title="mod.ts" -import * as uuid from "uuid"; - -console.log(uuid.v4()); -``` - -### Supported package registries and specifiers - -We support the following registries: - -| Registry | Specifier | -| -------- | --------- | -| JSR | jsr: | -| npm | npm: | - -## Understanding Package Versions - -When using Deno add, you can specify a version range for the package you are -adding. This is done using the `@` symbol followed by a version range specifier, -and follows the [semver](https://semver.org/) versioning scheme. - -```bash -deno add @scopename/mypackage # latest version -deno add @scopename/mypackage@16.1.0 # exact version -deno add @scopename/mypackage@^16.1.0 # latest patch version 16.x -deno add @scopename/mypackage@~16.1.0 # latest version that doesn't increment the first non-zero portion -``` - -## Importing by URL - -Deno also supports import statements that reference URLs, either directly: - -```js -import { Application } from "https://deno.land/x/oak/mod.ts"; -``` - -or part of your `deno.json` import map: - -```json -{ - "imports": { - "oak": "https://deno.land/x/oak/mod.ts" - } -} -``` - -Supporting URL imports enables us to support the following JavaScript CDNs, as -they provide URL access to JavaScript modules: - -- [deno.land/x](https://deno.land/x) -- [esm.sh](https://esm.sh) -- [unpkg.com](https://unpkg.com) - -URL imports are useful if you have a small, often single file, Deno project that -doesn't require any other configuration because you can avoid having a -`Deno.json` file at all. It's not advised to use this style of import in larger -applications as you may end up with version conflicts (where different files use -different version specifiers). - -From a security perspective, the contents of files at URLs can change, so we do -not generally recommend this approach for third-party components. - -URL imports remain supported, **but we recommend using a package registry for -the best experience.** - -### Overriding URL imports - -The other situation where import maps can be very useful is to override URL -imports in specific modules. - -Let's say you want to override a `https://deno.land/x/my-library@1.0.0/mod.ts` -specifier that is used inside files coming from `https://deno.land/x/example/` -to a local patched version. You can do this by using a scope in the import map -that looks something like this: - -```json -{ - "imports": { - "example/": "https://deno.land/x/example/" - }, - "scopes": { - "https://deno.land/x/example/": { - "https://deno.land/x/my-library@1.0.0/mod.ts": "./patched/mod.ts" - } - } -} -``` - -_It is important to note that URL imports have no notion of packages. Only the -import map at the root of your project is used. Import maps used inside URL -dependencies are ignored._ - -## Proxies - -Deno supports proxies for module downloads and the Web standard `fetch` API. - -Proxy configuration is read from environmental variables: `HTTP_PROXY`, -`HTTPS_PROXY` and `NO_PROXY`. - -In case of Windows, if environment variables are not found Deno falls back to -reading proxies from registry. diff --git a/runtime/manual/basics/modules/integrity_checking.md b/runtime/manual/basics/modules/integrity_checking.md deleted file mode 100644 index b454a88e1..000000000 --- a/runtime/manual/basics/modules/integrity_checking.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Integrity Checking & Lock Files" ---- - -## Introduction - -Let's say your module depends on remote module `https://some.url/a.ts`. When you -compile your module for the first time `a.ts` is retrieved, compiled and cached. -It will remain this way until you run your module on a new machine (say in -production) or reload the cache (through `deno cache --reload` for example). But -what happens if the content in the remote url `https://some.url/a.ts` is -changed? This could lead to your production module running with different -dependency code than your local module. Deno's solution to avoid this is to use -integrity checking and lock files. - -## Caching and lock files - -Deno can store and check subresource integrity for modules using a small JSON -file. To opt into a lock file, either: - -1. Create a `deno.json` file in the current or an ancestor directory, which will - automatically create an additive lockfile at `deno.lock`. -2. Use the `--lock=deno.lock` to enable and specify lock file checking. To - update or create a lock use `--lock=deno.lock --frozen=false`. The - `--lock=deno.lock` tells Deno what the lock file to use is, while the - `--frozen=false` is used to output dependency hashes to the lock file. - -A `deno.lock` might look like this, storing a hash of the file against the -dependency: - -```json -{ - "https://deno.land/std@0.224.0/textproto/mod.ts": "3118d7a42c03c242c5a49c2ad91c8396110e14acca1324e7aaefd31a999b71a4", - "https://deno.land/std@0.224.0/io/util.ts": "ae133d310a0fdcf298cea7bc09a599c49acb616d34e148e263bcb02976f80dee", - "https://deno.land/std@0.224.0/async/delay.ts": "35957d585a6e3dd87706858fb1d6b551cb278271b03f52c5a2cb70e65e00c26a", - ... -} -``` - -### Auto-generated lockfile - -As mentioned above, when a Deno configuration file is resolved (ex. `deno.json`) -then an additive lockfile will be automatically generated. By default, the path -of this lockfile will be `deno.lock`. You can change this path by updating your -`deno.json` to specify this: - -```jsonc -{ - "lock": "./lock.file" -} -``` - -Or disable automatically creating and validating a lockfile by specifying: - -```jsonc -{ - "lock": false -} -``` - -### Freezing the lockfile - -The `--frozen` (alias `--frozen-lockfile`) flag causes Deno to error whenever an -attempt to update the lockfile is made. You can also enable the same behavior by -specifying the following configuration in your `deno.json` file instead: - -```json -{ - "lock": { - "frozen": true - } -} -``` - -For example, say you're importing `npm:chalk@5.3.0` while using `--frozen`, and -you later tried to import `npm:chalk@5.2.0`. Instead of quitely adding a second, -out-of-date version of `chalk` to your dependency tree, Deno would fail, showing -that `npm:chalk@5.2.0` would've otherwise been added to your lockfile. - -``` -error: The lockfile is out of date. Run `deno cache --frozen=false` or rerun with `--frozen=false` to update it. -changes: - 7 | - "npm:chalk@5.3.0": "npm:chalk@5.3.0" - 7 | + "npm:chalk@5.2.0": "npm:chalk@5.2.0", - 8 | + "npm:chalk@5.3.0": "npm:chalk@5.3.0" -21 | - "chalk@5.3.0": { -22 | + "chalk@5.2.0": { -23 | + "integrity": "sha512-ree3Gqw/nazQAPuJJEy+avdl7QfZMcUvmHIKgEZkGL+xOBzRvup5Hxo6LHuMceSxOabuJLJm5Yp/92R9eMmMvA==", -24 | + "dependencies": {} -25 | + }, -26 | + "chalk@5.3.0": { -``` - -If you intend to instead update you lockfile, you can specify `--frozen=false`, -which will update the lockfile without error. You can also enable the same -functionality through the following `deno.json` configuration: - -```json -{ - "lock": { - "frozen": false - } -} -``` - -> [!NOTE] `--lock-write` was replaced by `--frozen=false` was replaced in -> [Deno 1.45](https://deno.com/blog/v1.45#frozen-lockfile). - -## Runtime verification - -Like caching above, you can also use lock files during use of the `deno run` sub -command, validating the integrity of any locked modules during the run. Remember -that this only validates against dependencies previously added to the lock file. - -You can take this a step further as well by using the `--cached-only` flag to -require that remote dependencies are already cached. - -```shell -deno run --lock=deno.lock --cached-only mod.ts -``` - -This will fail if there are any dependencies in the dependency tree for mod.ts -which are not yet cached. diff --git a/runtime/manual/basics/modules/proxies.md b/runtime/manual/basics/modules/proxies.md deleted file mode 100644 index d07b29de3..000000000 --- a/runtime/manual/basics/modules/proxies.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Proxies" ---- - -Deno supports proxies for module downloads and the Web standard `fetch` API. - -Proxy configuration is read from environmental variables: `HTTP_PROXY`, -`HTTPS_PROXY` and `NO_PROXY`. - -In case of Windows, if environment variables are not found Deno falls back to -reading proxies from registry. diff --git a/runtime/manual/basics/modules/publishing_modules.md b/runtime/manual/basics/modules/publishing_modules.md deleted file mode 100644 index c5cf9bf23..000000000 --- a/runtime/manual/basics/modules/publishing_modules.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Publishing Modules -oldUrl: - - /runtime/manual/advanced/publishing/dnt/ - - /runtime/manual/advanced/publishing/ ---- - -Any Deno program that defines an export can be published as a module. This -allows other developers to import and use your code in their own projects. -Modules can be published to [JSR](https://jsr.io). - -## Configuring your module - -To configure your module for publishing, you need to ensure you have the -following properties defined in a `deno.json` file at the root of your project: - -```json title="deno.json" -{ - "name": "@my-scope/my-module", - "version": "1.0.0", - "exports": "./mod.ts" -} -``` - -In order to publish, you need a -[JSR scope and a new package](https://jsr.io/docs/publishing-packages#creating-a-scope-and-package) -to identify your module. You can create your scope and package at -[jsr.io/new](https://jsr.io/new). - -The `name` property in your `deno.json` file is a concatenation of your scope -and package name, separated by a `/`. The `exports` property should point to the -main entry point of your module. - -## Publishing your module - -Packages can be published to JSR in the CLI with the -[`deno publish` command](https://jsr.io/docs/publishing-packages#publishing-from-your-local-machine). - -To publish your module, run the following command in the root of your project: - -```bash -deno publish -``` - -Before publishing, you can use the `--dry-run` flag locally to test the -publishing process, without actually publishing your module. This will print out -a list of all of the files that will be published and can be used to verify that -your module is set up correctly: - -```bash -deno publish --dry-run -``` - -## Authentication - -You can publish your modules from the browser at -[jsr.io/new](https://jsr.io/new). - -You can also publish your package with a GitHub Action. Link your repository by -following the instructions at -[jsr.io/docs/publishing-packages#publishing-from-github-actions](https://jsr.io/docs/publishing-packages#publishing-from-github-actions). -This will allow you to publish packages without needing to provide an auth token -and instead uses OIDC authentication from GitHub itself. - -## Publishing for Node - -Library authors may want to make their Deno modules available to Node.js users. -This is possible by using the [dnt](https://github.com/denoland/dnt) build tool. - -dnt allows you to develop your Deno module mostly as-is and use a single Deno -script to build, type check, and test an npm package in an output directory. -Once built, you only need to `npm publish` the output directory to distribute it -to Node.js users. - -For more details, see -[https://github.com/denoland/dnt](https://github.com/denoland/dnt). diff --git a/runtime/manual/basics/modules/reloading_modules.md b/runtime/manual/basics/modules/reloading_modules.md deleted file mode 100644 index bd947e04d..000000000 --- a/runtime/manual/basics/modules/reloading_modules.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Reloading Modules" -oldUrl: - - /runtime/manual/linking_to_external_code/reloading_modules - - /runtime/manual/linkingtoexternal_code ---- - -By default, Deno uses a global cache directory (`DENO_DIR`) for downloaded -dependencies. This cache is shared across all projects. - -You can force deno to refetch and recompile modules into the cache using the -`--reload` flag of the `deno cache` or `deno run` subcommand. - -```bash -# Reload everything -deno cache --reload my_module.ts -# Reload a specific module -deno cache --reload=jsr:@std/fs my_module.ts -``` - -## Vendoring - -To create a cache directory per project, set `"vendor": true` in your -`deno.json`. [Read more about vendoring](../vendoring/). From 06af857b33ea246d0ab65db2a6d35848b5670993 Mon Sep 17 00:00:00 2001 From: Jo Franchetti Date: Mon, 2 Sep 2024 12:10:27 +0200 Subject: [PATCH 02/16] fix: update links --- runtime/_data.ts | 13 ++----------- runtime/fundamentals/modules.md | 11 ++++++++--- runtime/manual/advanced/continuous_integration.md | 6 ++++-- 3 files changed, 14 insertions(+), 16 deletions(-) diff --git a/runtime/_data.ts b/runtime/_data.ts index 31261fcf6..7f5aeccb2 100644 --- a/runtime/_data.ts +++ b/runtime/_data.ts @@ -18,17 +18,7 @@ export const sidebar = [ items: [ "/runtime/fundamentals/typescript/", "/runtime/fundamentals/security/", - { - label: "Using & Publishing Modules", - items: [ - "/runtime/manual/basics/modules/", - "/runtime/manual/basics/modules/publishing_modules/", - "/runtime/manual/basics/modules/reloading_modules/", - "/runtime/manual/basics/modules/integrity_checking/", - "/runtime/manual/advanced/private_repositories/", - "/runtime/manual/advanced/http_imports/", - ], - }, + "/runtime/fundamentals/modules/", "/runtime/fundamentals/configuration/", "/runtime/fundamentals/standard_library/", "/runtime/fundamentals/web_dev/", @@ -211,6 +201,7 @@ export const sidebar = [ { title: "Advanced Topics", items: [ + "/runtime/manual/advanced/private_repositories/", { label: "Deploying & Embedding Deno", items: [ diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index d49799f76..99c4226b9 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -7,11 +7,15 @@ oldUrl: - /runtime/manual/basics/modules/proxies/ - /runtime/manual/basics/modules/publishing_modules/ - /runtime/manual/basics/modules/reloading_modules/ + - /runtime/manual/basics/vendoring/ + - /runtime/manual/advanced/http_imports/ - /runtime/manual/advanced/publishing/dnt/ - /runtime/manual/advanced/publishing/ - - /runtime/manual/basics/vendoring/ + - /runtime/manual/examples/manage_dependencies - /runtime/manual/node/cdns.md - - /runtime/manual/advanced/http_imports/ + - /runtime/manual/linking_to_external_code + - /runtime/manual/linking_to_external_code/reloading_modules + - /runtime/fundamentals/esm.sh --- Deno uses @@ -172,7 +176,8 @@ console.log(uuid.v4()); ## Importing modules from HTTP URLs Deno supports importing modules from HTTP URLs. Note that npm packages can be -directly imported via the [`npm:` specifier](TODO:specifiers-link). +directly imported via the +[`npm:` specifier](/runtime/manual/node/npm_specifiers/). ```typescript import { render } from "https://esm.sh/preact"; diff --git a/runtime/manual/advanced/continuous_integration.md b/runtime/manual/advanced/continuous_integration.md index 501f3587f..21581c040 100644 --- a/runtime/manual/advanced/continuous_integration.md +++ b/runtime/manual/advanced/continuous_integration.md @@ -15,6 +15,7 @@ On this page we will discuss: - [Speeding up Deno pipelines](#speeding-up-deno-pipelines) - [Reducing repetition](#reducing-repetition) - [Caching dependencies](#caching-dependencies) + - [Clearing the cache](#clearing-the-cache) ## Setting up a basic pipeline @@ -178,8 +179,9 @@ key: ${{ hashFiles('deno.lock') }} ``` To make this work you will also need a have a lockfile in your Deno project, -which is discussed in detail [here](TODO:integrity-checking-link). Now, if the -contents of `deno.lock` are changed, a new cache will be made and used in +which is discussed in detail +[here](/runtime/fundamentals/modules/#integrity-checking-and-lock-files). Now, +if the contents of `deno.lock` are changed, a new cache will be made and used in subsequent pipeline runs thereafter. To demonstrate, let's say you have a project that uses the logger from From ea8a51ea01ba898171c269c6f3ebc77cbc424225 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 12:43:59 +0200 Subject: [PATCH 03/16] docs: update freezing lockfiile section --- runtime/fundamentals/modules.md | 70 ++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 99c4226b9..a7c97e69a 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -339,14 +339,14 @@ By default, Deno uses a global cache directory (`DENO_DIR`) for downloaded dependencies. This cache is shared across all projects. You can force deno to refetch and recompile modules into the cache using the -`--reload` flag of the `deno cache` or `deno run` subcommand. +`--reload` flag. ```bash # Reload everything -deno cache --reload my_module. +deno run --reload my_module.ts # Reload a specific module -deno cache --reload=jsr:@std/fs my_module.ts +deno run --reload=jsr:@std/fs my_module.ts ``` ## Vendoring @@ -399,10 +399,9 @@ lock file, either: 1. Create a `deno.json` file in the current or an ancestor directory, which will automatically create an additive lockfile at `deno.lock`. 2. Use the `--lock=deno.lock` flag to enable and specify lock file checking. To - update or create a lock use `--lock=deno.lock --lock-write`. The + update or create a lock use `--lock=deno.lock --frozen=false`. The `--lock=deno.lock` tells Deno what the lock file to use is, while the - `--lock-write` is used to output dependency hashes to the lock file - (`--lock-write` must be used in conjunction with `--lock`). + `--frozen=false` is used to output dependency hashes to the lock file. A `deno.lock` might look like this, storing a hash of the file against the dependency: @@ -437,37 +436,54 @@ Or disable automatically creating and validating a lockfile by specifying: } ``` -### Using `--lock` and `--lock-write` flags +### Freezing the lockfile -You may have a file that imports a dependency and looks something like this: +The `--frozen` (alias `--frozen-lockfile`) flag causes Deno to error whenever an +attempt to update the lockfile is made. You can also enable the same behavior by +specifying the following configuration in your `deno.json` file instead: -```ts title="src/deps.ts" -export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts"; +```json +{ + "lock": { + "frozen": true + } +} ``` -To create a lock file, you can use the `--lock` and `--lock-write` flags: +For example, say you're importing `npm:chalk@5.3.0` while using `--frozen`, and +you later tried to import `npm:chalk@5.2.0`. Instead of quitely adding a second, +out-of-date version of `chalk` to your dependency tree, Deno would fail, showing +that `npm:chalk@5.2.0` would've otherwise been added to your lockfile. -```shell -# Create/update the lock file "deno.lock". -deno cache --lock=deno.lock --lock-write src/deps.ts - -# Include it when committing to source control. -git add -u deno.lock -git commit -m "feat: Add support for xyz using xyz-lib" -git push +``` +error: The lockfile is out of date. Run `deno cache --frozen=false` or rerun with `--frozen=false` to update it. +changes: + 7 | - "npm:chalk@5.3.0": "npm:chalk@5.3.0" + 7 | + "npm:chalk@5.2.0": "npm:chalk@5.2.0", + 8 | + "npm:chalk@5.3.0": "npm:chalk@5.3.0" +21 | - "chalk@5.3.0": { +22 | + "chalk@5.2.0": { +23 | + "integrity": "sha512-ree3Gqw/nazQAPuJJEy+avdl7QfZMcUvmHIKgEZkGL+xOBzRvup5Hxo6LHuMceSxOabuJLJm5Yp/92R9eMmMvA==", +24 | + "dependencies": {} +25 | + }, +26 | + "chalk@5.3.0": { ``` -Collaborator on another machine -- in a freshly cloned project tree: - -```shell -# Download the project's dependencies into the machine's cache, integrity -# checking each resource. -deno cache --reload --lock=deno.lock src/deps.ts +If you intend to instead update you lockfile, you can specify `--frozen=false`, +which will update the lockfile without error. You can also enable the same +functionality through the following `deno.json` configuration: -# Done! You can proceed safely. -deno test --allow-read src +```json +{ + "lock": { + "frozen": false + } +} ``` +> [!NOTE] `--lock-write` was replaced by `--frozen=false` was replaced in +> [Deno 1.45](https://deno.com/blog/v1.45#frozen-lockfile). + ### Runtime verification Like caching above, you can also use lock files during use of the `deno run` sub From 0fd3d4cbd28a8fa54b0394db7daf3a42c982549a Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 15:53:19 +0200 Subject: [PATCH 04/16] docs: shorten module menu entry label --- runtime/_data.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/runtime/_data.ts b/runtime/_data.ts index 7f5aeccb2..4fcb80d37 100644 --- a/runtime/_data.ts +++ b/runtime/_data.ts @@ -18,7 +18,10 @@ export const sidebar = [ items: [ "/runtime/fundamentals/typescript/", "/runtime/fundamentals/security/", - "/runtime/fundamentals/modules/", + { + label: "Modules", + id: "/runtime/fundamentals/modules/", + }, "/runtime/fundamentals/configuration/", "/runtime/fundamentals/standard_library/", "/runtime/fundamentals/web_dev/", From d4ebaba3ac57ac144330715ec72550676befdd47 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 15:53:29 +0200 Subject: [PATCH 05/16] docs: rework modules page --- runtime/fundamentals/modules.md | 259 +++++++++++--------------------- 1 file changed, 89 insertions(+), 170 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index a7c97e69a..c48591c0f 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -20,15 +20,15 @@ oldUrl: Deno uses [ECMAScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) -exclusively. +as its default module system to align with modern JavaScript standards and to +promote a more efficient and consistent development experience. It's the +official standard for JavaScript modules, allows for better tree-shaking, +improved tooling integration, and native support across different environments. -Since 2015, ES Modules have been an integral part of the JavaScript -specification, enabling seamless module usage directly in the browser. Unlike -CommonJS, which is not natively supported in browsers, ES Modules provide a -standardized way to manage dependencies and modularize code. Deno aims to narrow -the gap between browser and server environments by fully embracing ES Modules, -ensuring a more consistent and streamlined development experience across both -platforms. +By adopting ECMAScript modules, Deno ensures compatibility with the evolving +JavaScript ecosystem, providing developers with a streamlined and predictable +module system that eliminates the complexities associated with legacy module +formats like CommonJS. ## Importing modules @@ -41,165 +41,97 @@ export function add(a: number, b: number): number { ``` ```ts title="main.ts" +// imports the `calc.ts` module next to this file import { add } from "./calc.ts"; console.log(add(1, 2)); // 3 ``` You can run this example by calling `deno run main.ts` in the directory that -contains `main.ts` and `calc.ts`. +contains both `main.ts` and `calc.ts`. -## Adding third party modules and libraries to deno.json +With ECMAScript modules, local import specifiers must always included the full +file extension. It cannot be omitted. -Using remote modules (downloaded from a registry) in Deno uses the same `import` -syntax as your local code. +```ts title="example.ts" +// WRONG: missing file extension +import { add } from "./calc"; -The modules that you add to your project are tracked as `imports` in -`deno.json` - we call this the import map. - -```json title="deno.json" -{ - "imports": { - "@scopename/mypackage": "jsr:@scopename/mypackage@^16.1.0" - } -} -``` - -You can add modules using the `deno add` subcommand: - -```sh -# Add the latest version of the module to deno.json -$ deno add @luca/cases -Add @luca/cases - jsr:@luca/cases@^1.0.0 -``` - -```json title="deno.json" -{ - "imports": { - "@luca/cases": "jsr:@luca/cases@^1.0.0" - } -} -``` - -The `deno add` command will automatically add the latest version of the module -you requested to your project imports, unless you specify an exact version: - -```sh -# Passing an exact version -$ deno add @luca/cases@1.0.0 -Add @luca/cases - jsr:@luca/cases@^1.0.0 -``` - -## Local imports - -When importing local modules, use relative paths that start with `./` or `../` -and include the full file extension. This means you need to specify `.ts`, -`.js`, `.tsx`, `.jsx`, or `.mjs` extensions explicitly. This ensures that Deno -correctly resolves the module location relative to the current file. For -example: - -```ts -// Always include the file extension +// CORRECT: includes file extension import { add } from "./calc.ts"; ``` -## Using installed modules +## Importing third party modules and libraries -Once a package is added to the import map in `deno.json`, you can import the -module by its name, and Deno will automatically resolve the module. For example: +Using third modules in Deno uses the same `import` syntax as your local code. +Third party modules are typically imported from a remote registry and start with +`jsr:` , `npm:` or `https://` for URL imports. ```ts title="main.ts" -import { camelCase } from "@luca/cases"; - -camelCase("hello world"); // "helloWorld" +import { camelCase } from "jsr:@luca/cases@1.0.0"; +import { say } from "npm:cowsay@1.6.0"; +import { pascalCase } from "https://deno.land/x/case/mod.ts"; ``` -## Package Registries - -Deno recommends that you use [JSR](https://jsr.io/), the JavaScript registry, to -publish and manage your modules for the best publishing experience. JSR offers -automatic documentation generation, semver resolution and improved performance -for TypeScript code. Deno also supports -[other platforms](https://jsr.io/docs/other-registries) for publishing modules, -such as npm, and JavaScript CDNs like deno.land/x, esm.h and unpkg.com +You'll find most Deno-related code on [JSR](https://jsr.io), which is the +recommended registry to use with Deno. -By default when you use the CLI, the package will be resolved from JSR. - -```bash -deno add @scopename/mypackage -``` +## Managing third party modules and libraries -The resulting import map contains the `jsr:` import specifier in the resulting -`deno.json` file. +Typing out the module with the full version specifier can become tedious real +fast when you're importing them from multiple files. We can centralize the +management of remote modules via the `imports` key in `deno.json`. The `imports` +key is used to remap specifiers. We call this the import map. -```json +```json title="deno.json" { "imports": { - "@scopename/mypackage": "jsr:@scopename/mypackage@^16.1.0" + "@luca/cases": "jsr:@luca/cases@^1.0.0", + "cowsay": "npm:cowsay@^1.6.0", + "cases": "https://deno.land/x/case/mod.ts" } } ``` -Deno supports the following registries: - -| Registry | Specifier | -| -------- | --------- | -| JSR | jsr: | -| npm | npm: | - -To import a package from `npm` you need to prefix the package name with the -`npm:` specifier: - -```bash -$ deno add npm:uuid -Add uuid - npm:uuid@^10.0.0 -``` - -The resulting `deno.json` will contain the following import: +With the remapped specifiers our code gets a bit simpler: -```json -{ - "imports": { - "uuid": "npm:uuid@^10.0.0" - } -} +```ts title="main.ts" +import { camelCase } from "@luca/cases"; +import { say } from "cowsay"; +import { pascalCase } from "cases"; ``` -You can then use the npm module by importing it by name from the import map. +The remapped name can be any valid specifier. It's a very powerful feature in +Deno that can remap anything. Learn more about everything the import map can do +[here](/runtime/manual/basics/import_maps/). -```ts title="mod.ts" -import * as uuid from "uuid"; +## Adding dependencies with deno add -console.log(uuid.v4()); -``` - -## Importing modules from HTTP URLs - -Deno supports importing modules from HTTP URLs. Note that npm packages can be -directly imported via the -[`npm:` specifier](/runtime/manual/node/npm_specifiers/). +The installation process is made easier with the `deno add` subcommand. It will +automatically add the latest version of the package you requested to the +`imports` section in `deno.json`. -```typescript -import { render } from "https://esm.sh/preact"; +```sh +# Add the latest version of the module to deno.json +$ deno add @luca/cases +Add @luca/cases - jsr:@luca/cases@^1.0.0 ``` -You can also import modules from a URL by adding it to your `deno.json` import -map: - ```json title="deno.json" { "imports": { - "preact": "https://esm.sh/preact" + "@luca/cases": "jsr:@luca/cases@^1.0.0" } } ``` -URL imports should be used with caution, as they can introduce security risks. -When importing modules from a URL, you are trusting the server to serve the -correct code. If the server is compromised, it could serve malicious code to -your application. For this reason, it is recommended to **use URL imports only -from trusted sources**. They can also cause versioning issues if you import -different versions in different files. +You can also specify an exact version: + +```sh +# Passing an exact version +$ deno add @luca/cases@1.0.0 +Add @luca/cases - jsr:@luca/cases@^1.0.0 +``` ## Package Versions @@ -216,7 +148,7 @@ For example: @scopename/mypackage@~16.1.0 # latest version that doesn't increment the first non-zero portion ``` -### Import symbols +Here is an overview of all the ways you can specify a version or a range: | Symbol | Description | Example | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | @@ -231,7 +163,7 @@ For example: | `1.x` | Any minor and patch version within the major version 1. For example, `1.0.0`, `1.1.0`, `1.2.0`, etc. | `1.x` | | `*` | Any version is allowed. | `*` | -## Importing by URL +## URL imports Deno also supports import statements that reference URLs, either directly: @@ -262,11 +194,15 @@ doesn't require any other configuration because you can avoid having a applications as you may end up with version conflicts (where different files use different version specifiers). -From a security perspective, the contents of files at URLs can change, so we do -not generally recommend this approach for third-party components. +:::info -URL imports remain supported, **but we recommend using a package registry for -the best experience.** +Use URL imports with caution, and only **from trusted sources**. If the server +is compromised, it could serve malicious code to your application. They can also +cause versioning issues if you import different versions in different files. URL +imports remain supported, **but we recommend using a package registry for the +best experience.** + +::: ### Overriding URL imports @@ -436,53 +372,36 @@ Or disable automatically creating and validating a lockfile by specifying: } ``` -### Freezing the lockfile +### Using `--lock` and `--lock-write` flags -The `--frozen` (alias `--frozen-lockfile`) flag causes Deno to error whenever an -attempt to update the lockfile is made. You can also enable the same behavior by -specifying the following configuration in your `deno.json` file instead: +You may have a file that imports a dependency and looks something like this: -```json -{ - "lock": { - "frozen": true - } -} +```ts title="src/deps.ts" +export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts"; ``` -For example, say you're importing `npm:chalk@5.3.0` while using `--frozen`, and -you later tried to import `npm:chalk@5.2.0`. Instead of quitely adding a second, -out-of-date version of `chalk` to your dependency tree, Deno would fail, showing -that `npm:chalk@5.2.0` would've otherwise been added to your lockfile. +To create a lock file, you can use the `--lock` and `--lock-write` flags: -``` -error: The lockfile is out of date. Run `deno cache --frozen=false` or rerun with `--frozen=false` to update it. -changes: - 7 | - "npm:chalk@5.3.0": "npm:chalk@5.3.0" - 7 | + "npm:chalk@5.2.0": "npm:chalk@5.2.0", - 8 | + "npm:chalk@5.3.0": "npm:chalk@5.3.0" -21 | - "chalk@5.3.0": { -22 | + "chalk@5.2.0": { -23 | + "integrity": "sha512-ree3Gqw/nazQAPuJJEy+avdl7QfZMcUvmHIKgEZkGL+xOBzRvup5Hxo6LHuMceSxOabuJLJm5Yp/92R9eMmMvA==", -24 | + "dependencies": {} -25 | + }, -26 | + "chalk@5.3.0": { +```shell +# Create/update the lock file "deno.lock". +deno cache --lock=deno.lock --lock-write src/deps.ts + +# Include it when committing to source control. +git add -u deno.lock +git commit -m "feat: Add support for xyz using xyz-lib" +git push ``` -If you intend to instead update you lockfile, you can specify `--frozen=false`, -which will update the lockfile without error. You can also enable the same -functionality through the following `deno.json` configuration: +Collaborator on another machine -- in a freshly cloned project tree: -```json -{ - "lock": { - "frozen": false - } -} -``` +```shell +# Download the project's dependencies into the machine's cache, integrity +# checking each resource. +deno cache --reload --lock=deno.lock src/deps.ts -> [!NOTE] `--lock-write` was replaced by `--frozen=false` was replaced in -> [Deno 1.45](https://deno.com/blog/v1.45#frozen-lockfile). +# Done! You can proceed safely. +deno test --allow-read src +``` ### Runtime verification From 6e914c78e87e2bf6d4eeeda8e191ebe09690cb91 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 16:05:21 +0200 Subject: [PATCH 06/16] docs: move proxies section --- runtime/fundamentals/modules.md | 14 ---------- .../getting_started/setup_your_environment.md | 12 +++++---- runtime/manual/tools/env_variables.md | 27 +++++++++++++------ 3 files changed, 26 insertions(+), 27 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index c48591c0f..74180adb0 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -4,7 +4,6 @@ oldUrl: - /runtime/manual/basics/modules/ - /runtime/manual/basics/modules/integrity_checking/ - /runtime/manual/basics/modules/module_metadata/ - - /runtime/manual/basics/modules/proxies/ - /runtime/manual/basics/modules/publishing_modules/ - /runtime/manual/basics/modules/reloading_modules/ - /runtime/manual/basics/vendoring/ @@ -234,19 +233,6 @@ project is used. Import maps used inside URL dependencies are ignored. ::: -## Proxies - -Deno is able to handle network requests through a proxy server, useful for -various reasons such as security, caching, or accessing resources behind a -firewall. The runtime supports supports proxies for module downloads and the Web -standard `fetch` API. - -Deno reads proxy configuration from environment variables: `HTTP_PROXY`, -`HTTPS_PROXY` and `NO_PROXY`. - -In case of Windows, if environment variables are not found, Deno falls back to -reading proxies from the registry. - ## Publishing modules Any Deno program that defines an export can be published as a module. This diff --git a/runtime/manual/getting_started/setup_your_environment.md b/runtime/manual/getting_started/setup_your_environment.md index bfaf5f4be..2b052cdda 100644 --- a/runtime/manual/getting_started/setup_your_environment.md +++ b/runtime/manual/getting_started/setup_your_environment.md @@ -1,5 +1,7 @@ --- title: "Set Up Your Environment" +oldUrl: + - /runtime/manual/basics/modules/proxies/ --- The Deno CLI contains a lot of the tools that are commonly needed for developing @@ -412,7 +414,7 @@ There are several environment variables which can impact the behavior of Deno: specific certificate per TLS connection. - `DENO_CERT` - load a certificate authority from a PEM encoded file. This "overrides" the `--cert` option. See the - [Proxies](../basics/modules/proxies.md) section for more information. + [Proxies](/runtime/manual/tools/env_variables) section for more information. - `DENO_DIR` - this will set the directory where cached information from the CLI is stored. This includes items like cached remote modules, cached transpiled modules, language server cache information and persisted data from local @@ -427,9 +429,9 @@ There are several environment variables which can impact the behavior of Deno: available. - `DENO_WEBGPU_TRACE` - The directory to use for WebGPU traces. - `HTTP_PROXY` - The proxy address to use for HTTP requests. See the - [Proxies](../basics/modules/proxies.md) section for more information. + [Proxies](/runtime/manual/tools/env_variables) section for more information. - `HTTPS_PROXY` - The proxy address to use for HTTPS requests. See the - [Proxies](../basics/modules/proxies.md) section for more information. + [Proxies](/runtime/manual/tools/env_variables) section for more information. - `NO_COLOR` - If set, this will prevent the Deno CLI from sending ANSI color codes when writing to stdout and stderr. See the website [https://no-color.org](https://no-color.org/) for more information on this _de @@ -437,7 +439,7 @@ There are several environment variables which can impact the behavior of Deno: permission to read the environment variables by checking the value of `Deno.noColor`. - `NO_PROXY` - Indicates hosts which should bypass the proxy set in the other - environment variables. See the [Proxies](../basics/modules/proxies.md) section - for more information. + environment variables. See the [Proxies](/runtime/manual/tools/env_variables) + section for more information. - `NPM_CONFIG_REGISTRY` - The npm registry to use when loading modules via [npm specifiers](../node/npm_specifiers.md) diff --git a/runtime/manual/tools/env_variables.md b/runtime/manual/tools/env_variables.md index d528e4caf..995af376c 100644 --- a/runtime/manual/tools/env_variables.md +++ b/runtime/manual/tools/env_variables.md @@ -29,8 +29,7 @@ specific certificate per TLS connection. ### DENO_CERT Load a certificate authority from a PEM encoded file. This "overrides" the -`--cert` option. See the [Proxies](../basics/modules/proxies.md) section for -more information. +`--cert` option. See the [Proxies](#proxies) section for more information. ### DENO_DIR @@ -64,13 +63,13 @@ The directory to use for WebGPU traces. ### HTTP_PROXY -The proxy address to use for HTTP requests. See the -[Proxies](../basics/modules/proxies.md) section for more information. +The proxy address to use for HTTP requests. See the [Proxies](#proxies) section +for more information. ### HTTPS_PROXY -The proxy address to use for HTTPS requests. See the -[Proxies](../basics/modules/proxies.md) section for more information. +The proxy address to use for HTTPS requests. See the [Proxies](#proxies) section +for more information. ### NO_COLOR @@ -84,10 +83,22 @@ permission to read the environment variables by checking the value of ### NO_PROXY Indicates hosts which should bypass the proxy set in the other environment -variables. See the [Proxies](../basics/modules/proxies.md) section for more -information. +variables. See the [Proxies](#proxiesd) section for more information. ### NPM_CONFIG_REGISTRY The npm registry to use when loading modules via [npm specifiers](../node/npm_specifiers.md) + +## Proxies + +Deno is able to handle network requests through a proxy server, useful for +various reasons such as security, caching, or accessing resources behind a +firewall. The runtime supports supports proxies for module downloads and the Web +standard `fetch` API. + +Deno reads proxy configuration from environment variables: `HTTP_PROXY`, +`HTTPS_PROXY` and `NO_PROXY`. + +In case of Windows, if environment variables are not found, Deno falls back to +reading proxies from the registry. From c157cea9ed4b634b94685a702f4ccfc934f56dd5 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 16:15:00 +0200 Subject: [PATCH 07/16] docs: update module page --- runtime/fundamentals/modules.md | 35 ++++++++++++--------------------- 1 file changed, 13 insertions(+), 22 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 74180adb0..1e6786172 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -237,23 +237,14 @@ project is used. Import maps used inside URL dependencies are ignored. Any Deno program that defines an export can be published as a module. This allows other developers to import and use your code in their own projects. -Modules can be published to [JSR](https://jsr.io), the modern JavaScript and -TypeScript registry. Check out the -[JSR documentation on publishing modules](https://jsr.io/docs/publishing-packages) -for more information. +Modules can be published to: -## Publishing for Node.js - -You can make your Deno modules available to Node.js users with the -[dnt](https://github.com/denoland/dnt) build tool. - -dnt allows you to develop your Deno module mostly as-is and use a single Deno -script to build, type check, and test an npm package in an output directory. -Once built, you only need to `npm publish` the output directory to distribute it -to Node.js users. - -For more details, see -[https://github.com/denoland/dnt](https://github.com/denoland/dnt). +- [JSR](https://jsr.io) - recommended, supports TypeScript natively and + auto-generates documentation for you +- [npm](https://www.npmjs.com/) - use [dnt](https://github.com/denoland/dnt) to + create the npm package +- [deno.land/x](https://deno.com/add_module) - for URL imports, use JSR instead + if possible ## Reloading modules @@ -328,7 +319,7 @@ lock file, either: A `deno.lock` might look like this, storing a hash of the file against the dependency: -```json +```json title="deno.lock" { "https://deno.land/std@0.224.0/textproto/mod.ts": "3118d7a42c03c242c5a49c2ad91c8396110e14acca1324e7aaefd31a999b71a4", "https://deno.land/std@0.224.0/io/util.ts": "ae133d310a0fdcf298cea7bc09a599c49acb616d34e148e263bcb02976f80dee", @@ -344,7 +335,7 @@ then an additive lockfile will be automatically generated. By default, the path of this lockfile will be `deno.lock`. You can change this path by updating your `deno.json` to specify this: -```jsonc +```json title="deno.json" { "lock": "./lock.file" } @@ -352,13 +343,13 @@ of this lockfile will be `deno.lock`. You can change this path by updating your Or disable automatically creating and validating a lockfile by specifying: -```jsonc +```json title="deno.json" { "lock": false } ``` -### Using `--lock` and `--lock-write` flags +### Using `--lock` and `--frozen=false` flags You may have a file that imports a dependency and looks something like this: @@ -366,11 +357,11 @@ You may have a file that imports a dependency and looks something like this: export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts"; ``` -To create a lock file, you can use the `--lock` and `--lock-write` flags: +To create a lock file, you can use the `--lock` and `--frozen=false` flags: ```shell # Create/update the lock file "deno.lock". -deno cache --lock=deno.lock --lock-write src/deps.ts +deno cache --lock=deno.lock --frozen=false src/deps.ts # Include it when committing to source control. git add -u deno.lock From a8b3ac14eeee74206644208c8f2ed34f6ec96943 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 16:25:21 +0200 Subject: [PATCH 08/16] fix: broken links --- runtime/getting_started/command_line_interface.md | 2 +- runtime/manual/advanced/private_repositories.md | 2 +- runtime/manual/tools/index.md | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/runtime/getting_started/command_line_interface.md b/runtime/getting_started/command_line_interface.md index aa6a32fc7..a3b0f312f 100644 --- a/runtime/getting_started/command_line_interface.md +++ b/runtime/getting_started/command_line_interface.md @@ -162,7 +162,7 @@ Affect commands which can download resources to the cache: `deno cache`, ``` Find out more about these -[here](/runtime/manual/basics/modules/integrity_checking/). +[here](/runtime/fundamentals/modules/#integrity-checking-and-lock-files). ### Cache and compilation flags diff --git a/runtime/manual/advanced/private_repositories.md b/runtime/manual/advanced/private_repositories.md index da9a3ebfd..bfa427a26 100644 --- a/runtime/manual/advanced/private_repositories.md +++ b/runtime/manual/advanced/private_repositories.md @@ -5,7 +5,7 @@ title: "Private Modules and Repositories" :::note Not to be confused with -[private npm registries](/runtime/manual/node/private_registries/). +[private npm registries](/runtime/manual/node/private_registries). ::: diff --git a/runtime/manual/tools/index.md b/runtime/manual/tools/index.md index 3eeb0a1d8..8195533bc 100644 --- a/runtime/manual/tools/index.md +++ b/runtime/manual/tools/index.md @@ -29,8 +29,7 @@ Deno features before they are finalized. - [`deno jupyter`](./jupyter.md)- Deno kernel for Jupyter notebooks - [`deno lint`](./linter.md) - lint source files - [`deno lsp`](./lsp.md) - start the language server -- [`deno publish`](../basics/modules/publishing_modules.md) - publish a module - to JSR +- [`deno publish`](./publish.md) - publish a module to JSR - [`deno repl`](./repl.md) - read eval print loop - [`deno run`](./run.md) - run a JavaScript or TypeScript program - [`deno serve`](./serve.md) - run a server From 2f83a630a0ec3fcbb146213c4a08b2272cf023db Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 16:26:32 +0200 Subject: [PATCH 09/16] fix: fragment links --- .../getting_started/setup_your_environment.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/runtime/manual/getting_started/setup_your_environment.md b/runtime/manual/getting_started/setup_your_environment.md index 2b052cdda..0ac9adff2 100644 --- a/runtime/manual/getting_started/setup_your_environment.md +++ b/runtime/manual/getting_started/setup_your_environment.md @@ -414,7 +414,8 @@ There are several environment variables which can impact the behavior of Deno: specific certificate per TLS connection. - `DENO_CERT` - load a certificate authority from a PEM encoded file. This "overrides" the `--cert` option. See the - [Proxies](/runtime/manual/tools/env_variables) section for more information. + [Proxies](/runtime/manual/tools/env_variables#proxies) section for more + information. - `DENO_DIR` - this will set the directory where cached information from the CLI is stored. This includes items like cached remote modules, cached transpiled modules, language server cache information and persisted data from local @@ -429,9 +430,11 @@ There are several environment variables which can impact the behavior of Deno: available. - `DENO_WEBGPU_TRACE` - The directory to use for WebGPU traces. - `HTTP_PROXY` - The proxy address to use for HTTP requests. See the - [Proxies](/runtime/manual/tools/env_variables) section for more information. + [Proxies](/runtime/manual/tools/env_variables#proxies) section for more + information. - `HTTPS_PROXY` - The proxy address to use for HTTPS requests. See the - [Proxies](/runtime/manual/tools/env_variables) section for more information. + [Proxies](/runtime/manual/tools/env_variables#proxies) section for more + information. - `NO_COLOR` - If set, this will prevent the Deno CLI from sending ANSI color codes when writing to stdout and stderr. See the website [https://no-color.org](https://no-color.org/) for more information on this _de @@ -439,7 +442,8 @@ There are several environment variables which can impact the behavior of Deno: permission to read the environment variables by checking the value of `Deno.noColor`. - `NO_PROXY` - Indicates hosts which should bypass the proxy set in the other - environment variables. See the [Proxies](/runtime/manual/tools/env_variables) - section for more information. + environment variables. See the + [Proxies](/runtime/manual/tools/env_variables#proxies) section for more + information. - `NPM_CONFIG_REGISTRY` - The npm registry to use when loading modules via [npm specifiers](../node/npm_specifiers.md) From b4f7d57c5f182bf6698c440a2bc0622c38ffd7df Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 16:40:17 +0200 Subject: [PATCH 10/16] chore: fix typo Co-authored-by: Jo Franchetti --- runtime/fundamentals/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 1e6786172..81a464d6b 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -49,7 +49,7 @@ console.log(add(1, 2)); // 3 You can run this example by calling `deno run main.ts` in the directory that contains both `main.ts` and `calc.ts`. -With ECMAScript modules, local import specifiers must always included the full +With ECMAScript modules, local import specifiers must always include the full file extension. It cannot be omitted. ```ts title="example.ts" From 0106afce01d04fb76bdc29fa226c5beddf3bf0cd Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 16:41:05 +0200 Subject: [PATCH 11/16] docs: apply phrasing suggestion --- runtime/fundamentals/modules.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 81a464d6b..466136988 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -24,10 +24,10 @@ promote a more efficient and consistent development experience. It's the official standard for JavaScript modules, allows for better tree-shaking, improved tooling integration, and native support across different environments. -By adopting ECMAScript modules, Deno ensures compatibility with the evolving -JavaScript ecosystem, providing developers with a streamlined and predictable -module system that eliminates the complexities associated with legacy module -formats like CommonJS. +By adopting ECMAScript modules, Deno ensures compatibility with the +ever-evolving JavaScript ecosystem. For developers, this means a streamlined and +predictable module system that avoids the complexities associated with legacy +module formats like CommonJS. ## Importing modules @@ -112,7 +112,7 @@ automatically add the latest version of the package you requested to the ```sh # Add the latest version of the module to deno.json -$ deno add @luca/cases +$ deno add @luca/cases Add @luca/cases - jsr:@luca/cases@^1.0.0 ``` From 6f4d4c75912bdf6392a648cca4853f3771fa9308 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 17:03:53 +0200 Subject: [PATCH 12/16] docs: apply review suggestions Co-authored-by: Jo Franchetti --- runtime/fundamentals/modules.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 466136988..053de1811 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -62,7 +62,7 @@ import { add } from "./calc.ts"; ## Importing third party modules and libraries -Using third modules in Deno uses the same `import` syntax as your local code. +When working with third-party modules in Deno, use the same `import` syntax as you do for local code. Third party modules are typically imported from a remote registry and start with `jsr:` , `npm:` or `https://` for URL imports. @@ -72,15 +72,11 @@ import { say } from "npm:cowsay@1.6.0"; import { pascalCase } from "https://deno.land/x/case/mod.ts"; ``` -You'll find most Deno-related code on [JSR](https://jsr.io), which is the -recommended registry to use with Deno. +Deno recommends [JSR](https://jsr.io), the modern JavaScript registry, for third party modules. There, you'll find plenty of well documented ES modules for your projects, including the [Deno Standard Library](/runtime/fundamentals/standard_library/). ## Managing third party modules and libraries -Typing out the module with the full version specifier can become tedious real -fast when you're importing them from multiple files. We can centralize the -management of remote modules via the `imports` key in `deno.json`. The `imports` -key is used to remap specifiers. We call this the import map. +Typing out the module name with the full version specifier can become tedious when importing them in multiple files. You can centralize management of remote modules with an `imports` field in your `deno.json` file. We call this `imports` field the **import map**. ```json title="deno.json" { @@ -92,7 +88,7 @@ key is used to remap specifiers. We call this the import map. } ``` -With the remapped specifiers our code gets a bit simpler: +With remapped specifiers, the code looks cleaner: ```ts title="main.ts" import { camelCase } from "@luca/cases"; From 5d5638428a2c9bc81b81af221bfd88d9d954d1c5 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 17:20:50 +0200 Subject: [PATCH 13/16] chore: apply suggestions Co-authored-by: Jo Franchetti --- runtime/fundamentals/modules.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 053de1811..f498eee18 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -102,7 +102,7 @@ Deno that can remap anything. Learn more about everything the import map can do ## Adding dependencies with deno add -The installation process is made easier with the `deno add` subcommand. It will +The installation process is made easy with the `deno add` subcommand. It will automatically add the latest version of the package you requested to the `imports` section in `deno.json`. @@ -184,10 +184,9 @@ they provide URL access to JavaScript modules: - [unpkg.com](https://unpkg.com) URL imports are useful if you have a small, often single file, Deno project that -doesn't require any other configuration because you can avoid having a -`Deno.json` file at all. It's not advised to use this style of import in larger -applications as you may end up with version conflicts (where different files use -different version specifiers). +doesn't require any other configuration. With URL imports, you can avoid having a +`Deno.json` file at all. It is **not** advised to use this style of import in larger +applications however, as you may end up with version conflicts (where different files use different version specifiers). :::info @@ -326,18 +325,16 @@ dependency: ### Auto-generated lockfile -As mentioned above, when a Deno configuration file is resolved (ex. `deno.json`) -then an additive lockfile will be automatically generated. By default, the path -of this lockfile will be `deno.lock`. You can change this path by updating your +As mentioned above, when a Deno configuration file is resolved (eg. `deno.json`), a lockfile will be automatically generated. By default, the path +of this lockfile will be in the directory root - `deno.lock`. You can change this path by updating your `deno.json` to specify this: ```json title="deno.json" { "lock": "./lock.file" } -``` -Or disable automatically creating and validating a lockfile by specifying: +You can disable the automatic creation and validation of a lockfile by specifying: ```json title="deno.json" { @@ -382,7 +379,7 @@ Like caching above, you can also use lock files during use of the `deno run` sub command, validating the integrity of any locked modules during the run. Remember that this only validates against dependencies previously added to the lock file. -You can take this a step further as well by using the `--cached-only` flag to +You can take this a step further by using the `--cached-only` flag to require that remote dependencies are already cached. ```shell From 3082477dd5190647d8841747cb92c2361dcc86c8 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 17:21:17 +0200 Subject: [PATCH 14/16] chore: fix typo Co-authored-by: Jo Franchetti --- runtime/manual/tools/env_variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime/manual/tools/env_variables.md b/runtime/manual/tools/env_variables.md index 995af376c..609785f81 100644 --- a/runtime/manual/tools/env_variables.md +++ b/runtime/manual/tools/env_variables.md @@ -83,7 +83,7 @@ permission to read the environment variables by checking the value of ### NO_PROXY Indicates hosts which should bypass the proxy set in the other environment -variables. See the [Proxies](#proxiesd) section for more information. +variables. See the [Proxies](#proxies) section for more information. ### NPM_CONFIG_REGISTRY From f7c012156bb38d636c0486fad7aeaad7c9c6062a Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 17:21:27 +0200 Subject: [PATCH 15/16] chore: apply suggestion Co-authored-by: Jo Franchetti --- runtime/manual/tools/env_variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime/manual/tools/env_variables.md b/runtime/manual/tools/env_variables.md index 609785f81..1da0f9b8f 100644 --- a/runtime/manual/tools/env_variables.md +++ b/runtime/manual/tools/env_variables.md @@ -100,5 +100,5 @@ standard `fetch` API. Deno reads proxy configuration from environment variables: `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`. -In case of Windows, if environment variables are not found, Deno falls back to +On Windows, if environment variables are not found, Deno falls back to reading proxies from the registry. From f78ada10df43cf87f263b84e4be56996de68b924 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Mon, 2 Sep 2024 17:21:57 +0200 Subject: [PATCH 16/16] chore: fix formatting --- runtime/fundamentals/modules.md | 38 ++++++++++++++++----------- runtime/manual/tools/env_variables.md | 4 +-- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index f498eee18..d13185fb6 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -62,9 +62,9 @@ import { add } from "./calc.ts"; ## Importing third party modules and libraries -When working with third-party modules in Deno, use the same `import` syntax as you do for local code. -Third party modules are typically imported from a remote registry and start with -`jsr:` , `npm:` or `https://` for URL imports. +When working with third-party modules in Deno, use the same `import` syntax as +you do for local code. Third party modules are typically imported from a remote +registry and start with `jsr:` , `npm:` or `https://` for URL imports. ```ts title="main.ts" import { camelCase } from "jsr:@luca/cases@1.0.0"; @@ -72,11 +72,17 @@ import { say } from "npm:cowsay@1.6.0"; import { pascalCase } from "https://deno.land/x/case/mod.ts"; ``` -Deno recommends [JSR](https://jsr.io), the modern JavaScript registry, for third party modules. There, you'll find plenty of well documented ES modules for your projects, including the [Deno Standard Library](/runtime/fundamentals/standard_library/). +Deno recommends [JSR](https://jsr.io), the modern JavaScript registry, for third +party modules. There, you'll find plenty of well documented ES modules for your +projects, including the +[Deno Standard Library](/runtime/fundamentals/standard_library/). ## Managing third party modules and libraries -Typing out the module name with the full version specifier can become tedious when importing them in multiple files. You can centralize management of remote modules with an `imports` field in your `deno.json` file. We call this `imports` field the **import map**. +Typing out the module name with the full version specifier can become tedious +when importing them in multiple files. You can centralize management of remote +modules with an `imports` field in your `deno.json` file. We call this `imports` +field the **import map**. ```json title="deno.json" { @@ -184,9 +190,10 @@ they provide URL access to JavaScript modules: - [unpkg.com](https://unpkg.com) URL imports are useful if you have a small, often single file, Deno project that -doesn't require any other configuration. With URL imports, you can avoid having a -`Deno.json` file at all. It is **not** advised to use this style of import in larger -applications however, as you may end up with version conflicts (where different files use different version specifiers). +doesn't require any other configuration. With URL imports, you can avoid having +a `Deno.json` file at all. It is **not** advised to use this style of import in +larger applications however, as you may end up with version conflicts (where +different files use different version specifiers). :::info @@ -325,11 +332,12 @@ dependency: ### Auto-generated lockfile -As mentioned above, when a Deno configuration file is resolved (eg. `deno.json`), a lockfile will be automatically generated. By default, the path -of this lockfile will be in the directory root - `deno.lock`. You can change this path by updating your -`deno.json` to specify this: +As mentioned above, when a Deno configuration file is resolved (eg. +`deno.json`), a lockfile will be automatically generated. By default, the path +of this lockfile will be in the directory root - `deno.lock`. You can change +this path by updating your `deno.json` to specify this: -```json title="deno.json" +````json title="deno.json" { "lock": "./lock.file" } @@ -340,7 +348,7 @@ You can disable the automatic creation and validation of a lockfile by specifyin { "lock": false } -``` +```` ### Using `--lock` and `--frozen=false` flags @@ -379,8 +387,8 @@ Like caching above, you can also use lock files during use of the `deno run` sub command, validating the integrity of any locked modules during the run. Remember that this only validates against dependencies previously added to the lock file. -You can take this a step further by using the `--cached-only` flag to -require that remote dependencies are already cached. +You can take this a step further by using the `--cached-only` flag to require +that remote dependencies are already cached. ```shell deno run --lock=deno.lock --cached-only mod.ts diff --git a/runtime/manual/tools/env_variables.md b/runtime/manual/tools/env_variables.md index 1da0f9b8f..bbc9c7501 100644 --- a/runtime/manual/tools/env_variables.md +++ b/runtime/manual/tools/env_variables.md @@ -100,5 +100,5 @@ standard `fetch` API. Deno reads proxy configuration from environment variables: `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`. -On Windows, if environment variables are not found, Deno falls back to -reading proxies from the registry. +On Windows, if environment variables are not found, Deno falls back to reading +proxies from the registry.