Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

updating for deno future #681

Merged
merged 2 commits into from
Aug 6, 2024
Merged

updating for deno future #681

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
06d2990
updating for deno future
thisisjofrank Aug 6, 2024
663ecc4
updating modules and import maps
thisisjofrank Aug 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
updating modules and import maps
  • Loading branch information
@thisisjofrank
thisisjofrank committed Aug 6, 2024
commit 663ecc48db7b0706711a1a1d6e062af38c5a4aba
99 changes: 30 additions & 69 deletions runtime/manual/basics/import_maps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,70 +4,65 @@ oldUrl: /runtime/manual/basics/modules/import_maps/
---

In order for Deno to resolve a _bare specifier_ like `"react"` or `"lodash"`, it
needs to be told where to look for it. Does `"lodash"` refer to an npm module or
does it map to an https URL?
needs to be told where to look for it. Does `"lodash"` refer to an module in our
project or does it refer to a third party dependency? Deno needs to know where
to resolve the import specifier `lodash` to.

```ts
import lodash from "lodash";
```

Node and npm use `package.json` and the `node_modules` folder to do this
resolution. Deno, on the other hand, uses the
[import map](https://github.com/WICG/import-maps) standard.

To make the above `import lodash from "lodash"` work, add the following to the
[`deno.json` configuration file](../getting_started/configuration_file.md).
We can point Deno to the `lodash` package on npm, for example, by adding it to
the `"imports"` section in `deno.json`.

```json
{
"imports": {
"lodash": "https://esm.sh/[email protected].21"
"lodash": "npm:lodash@^4.17"
}
}
```

The `"imports"` section in `deno.json` is often referred to as an `import map`
that is based on the
[Import Maps Standard](https://github.com/WICG/import-maps).

You may have seen Node and npm use `package.json` and the `node_modules` folder
to do similar package resolution.

The `deno.json` file is auto-discovered and acts (among other things) as an
import map.
[Read more about `deno.json` here](../getting_started/configuration_file.md).

This also works with npm specifiers. Instead of the above, we could have also
written something similar in our `deno.json` configuration file:

```json
{
"imports": {
"lodash": "npm:lodash@^4.17"
}
}
```

## Example - Using the Deno Standard Library

Running the following:
Using third party modules is explained further in
[ECMAScript Modules](./modules/).

```bash
deno add @std/foo
```
## Custom path mappings

Produces the following:
The import map in `deno.json` can be used for more general path mapping of
specifiers. You can map an exact specifiers to a third party module or a file
directly, or you can map a part of an import specifier to a directory.

```json title="deno.json"
```jsonc title="deno.jsonc"
{
"imports": {
"@std/foo": "jsr:@std/foo@^1.2.3"
// Map to an exact file
"foo": "./some/long/path/foo.ts",
// Map to a directory, usage: "bar/file.ts"
"bar/": "./some/folder/bar/"
}
}
```

The import can then be used in your script:
Usage:

```ts title="bar.ts"
import { bar } from "@std/foo";

bar(1, 2);
```ts
import * as foo from "foo";
import * as bar from "bar/file.ts";
```

## Example - Using project root for absolute imports
Path mapping of import specifies is commonly used in larger code bases for
brevity.

To use your project root for absolute imports:

Expand All @@ -86,37 +81,3 @@ import { MyUtil } from "/util.ts";

This causes import specifiers starting with `/` to be resolved relative to the
import map's URL or file path.

## Overriding imports

The other situation where import maps can be very useful is to override imports
in specific modules.

Let's say you want to override a Deno Standard Library package import from
^1.2.3 to the latest in all of your imported modules, but for the
`https://deno.land/x/example/` module you want to use files in a local `patched`
directory. You can do this by using a scope in the import map that looks
something like this:

```json
{
"imports": {
"@std/foo": "jsr:@std/foo@^1.2.3"
},
"scopes": {
"https://deno.land/x/example/": {
"@std/foo": "./patched/mod.ts"
}
}
}
```

## Import Maps are for Applications

It is important to note that import map configuration files are
[only applied for Deno applications][scope], not in the various libraries that
your application code may import. This lets you, the application author, have
final say about what versions of libraries get included in your project.

[scope]: https://github.com/WICG/import-maps#scope
[Environment Variables]: /runtime/manual/basics/env_variables/
49 changes: 25 additions & 24 deletions runtime/manual/basics/modules/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,38 +199,39 @@ not generally recommend this approach for third-party components.
URL imports remain supported, **but we recommend using a package registry for
the best experience.**

## 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`.
### Overriding URL imports

In case of Windows, if environment variables are not found Deno falls back to
reading proxies from registry.
The other situation where import maps can be very useful is to override URL
imports in specific modules.

## Import paths
Let's say you want to override a `https://deno.land/x/[email protected]/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:

Inside `deno.json` you can specify an import map, which allows you to map a full
import path or a partial one to a different location.

```jsonc title="deno.jsonc"
```json
{
"imports": {
// Map to an exact file
"foo": "./some/long/path/foo.ts",
// Map to a directory, usage: "bar/file.ts"
"bar/": "./some/folder/bar/"
"example/": "https://deno.land/x/example/"
},
"scopes": {
"https://deno.land/x/example/": {
"https://deno.land/x/[email protected]/mod.ts": "./patched/mod.ts"
}
}
}
```

Usage:
_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._

```ts
import * as foo from "foo";
import * as bar from "bar/file.ts";
```
## Proxies

Deno supports proxies for module downloads and the Web standard `fetch` API.

Path mapping of import specifies is commonly used in larger code bases for
brevity.
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.