diff options
Diffstat (limited to 'docs/linking_to_external_code')
| -rw-r--r-- | docs/linking_to_external_code/import_maps.md | 53 | ||||
| -rw-r--r-- | docs/linking_to_external_code/integrity_checking.md | 85 | ||||
| -rw-r--r-- | docs/linking_to_external_code/private.md | 75 | ||||
| -rw-r--r-- | docs/linking_to_external_code/proxies.md | 9 | ||||
| -rw-r--r-- | docs/linking_to_external_code/reloading_modules.md | 33 |
5 files changed, 0 insertions, 255 deletions
diff --git a/docs/linking_to_external_code/import_maps.md b/docs/linking_to_external_code/import_maps.md deleted file mode 100644 index 881c3cb74..000000000 --- a/docs/linking_to_external_code/import_maps.md +++ /dev/null @@ -1,53 +0,0 @@ -## Import maps - -Deno supports [import maps](https://github.com/WICG/import-maps). - -You can use import maps with the `--import-map=<FILE>` CLI flag. - -Example: - -**import_map.json** - -```js -{ - "imports": { - "fmt/": "https://deno.land/std@$STD_VERSION/fmt/" - } -} -``` - -**color.ts** - -```ts -import { red } from "fmt/colors.ts"; - -console.log(red("hello world")); -``` - -Then: - -```shell -$ deno run --import-map=import_map.json color.ts -``` - -To use your project root for absolute imports: - -**import_map.json** - -```jsonc -{ - "imports": { - "/": "./", - "./": "./" - } -} -``` - -**main.ts** - -```ts -import { MyUtil } from "/util.ts"; -``` - -This causes import specifiers starting with `/` to be resolved relative to the -import map's URL or file path. diff --git a/docs/linking_to_external_code/integrity_checking.md b/docs/linking_to_external_code/integrity_checking.md deleted file mode 100644 index 3de2a5fca..000000000 --- a/docs/linking_to_external_code/integrity_checking.md +++ /dev/null @@ -1,85 +0,0 @@ -## 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. Use the `--lock=lock.json` to enable and specify lock file checking. To -update or create a lock use `--lock=lock.json --lock-write`. The -`--lock=lock.json` 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 `lock.json` might look like this, storing a hash of the file against the -dependency: - -```json -{ - "https://deno.land/std@$STD_VERSION/textproto/mod.ts": "3118d7a42c03c242c5a49c2ad91c8396110e14acca1324e7aaefd31a999b71a4", - "https://deno.land/std@$STD_VERSION/io/util.ts": "ae133d310a0fdcf298cea7bc09a599c49acb616d34e148e263bcb02976f80dee", - "https://deno.land/std@$STD_VERSION/async/delay.ts": "35957d585a6e3dd87706858fb1d6b551cb278271b03f52c5a2cb70e65e00c26a", - ... -} -``` - -A typical workflow will look like this: - -**src/deps.ts** - -```ts -// Add a new dependency to "src/deps.ts", used somewhere else. -export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts"; -``` - -Then: - -```shell -# Create/update the lock file "lock.json". -deno cache --lock=lock.json --lock-write src/deps.ts - -# Include it when committing to source control. -git add -u lock.json -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=lock.json src/deps.ts - -# Done! You can proceed safely. -deno test --allow-read src -``` - -### Runtime verification - -Like caching above, you can also use the `--lock=lock.json` option 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.json` file. New dependencies will be cached but -not validated. - -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=lock.json --cached-only mod.ts -``` - -This will fail if there are any dependencies in the dependency tree for mod.ts -which are not yet cached. - -<!-- TODO - Add detail on dynamic imports --> diff --git a/docs/linking_to_external_code/private.md b/docs/linking_to_external_code/private.md deleted file mode 100644 index 7ffadef04..000000000 --- a/docs/linking_to_external_code/private.md +++ /dev/null @@ -1,75 +0,0 @@ -## Private modules and repositories - -There maybe instances where you want to load a remote module that is located in -a _private_ repository, like a private repository on GitHub. - -Deno supports sending bearer tokens when requesting a remote module. Bearer -tokens are the predominant type of access token used with OAuth 2.0 and is -broadly supported by hosting services (e.g. GitHub, Gitlab, BitBucket, -Cloudsmith, etc.). - -### DENO_AUTH_TOKENS - -The Deno CLI will look for an environment variable named `DENO_AUTH_TOKENS` to -determine what authentication tokens it should consider using when requesting -remote modules. The value of the environment variable is in the format of a _n_ -number of tokens deliminated by a semi-colon (`;`) where each token is in the -format of `{token}@{hostname[:port]}`. - -For example a single token for would look something like this: - -```sh -DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land -``` - -And multiple tokens would look like this: - -```sh -DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land;f1e2d3c4b5a6@example.com:8080 -``` - -When Deno goes to fetch a remote module, where the hostname matches the hostname -of the remote module, Deno will set the `Authorization` header of the request to -the value of `Bearer {token}`. This allows the remote server to recognize that -the request is an authorized request tied to a specific authenticated user, and -provide access to the appropriate resources and modules on the server. - -### GitHub - -To be able to access private repositories on GitHub, you would need to issue -yourself a _personal access token_. You do this by logging into GitHub and going -under _Settings -> Developer settings -> Personal access tokens_: - - - -You would then choose to _Generate new token_ and give your token a description -and appropriate access: - - - -And once created GitHub will display the new token a single time, the value of -which you would want to use in the environment variable: - - - -In order to access modules that are contained in a private repository on GitHub, -you would want to use the generated token in the `DENO_AUTH_TOKENS` environment -variable scoped to the `raw.githubusercontent.com` hostname. For example: - -```sh -DENO_AUTH_TOKENS=a1b2c3d4e5f6@raw.githubusercontent.com -``` - -This should allow Deno to access any modules that the user who the token was -issued for has access to. - -When the token is incorrect, or the user does not have access to the module, -GitHub will issue a `404 Not Found` status, instead of an unauthorized status. -So if you are getting errors that the modules you are trying to access are not -found on the command line, check the environment variable settings and the -personal access token settings. - -In addition, `deno run -L debug` should print out a debug message about the -number of tokens that are parsed out of the environment variable. It will print -an error message if it feels any of the tokens are malformed. It won't print any -details about the tokens for security purposes. diff --git a/docs/linking_to_external_code/proxies.md b/docs/linking_to_external_code/proxies.md deleted file mode 100644 index 2186aa722..000000000 --- a/docs/linking_to_external_code/proxies.md +++ /dev/null @@ -1,9 +0,0 @@ -## 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/docs/linking_to_external_code/reloading_modules.md b/docs/linking_to_external_code/reloading_modules.md deleted file mode 100644 index e745996b1..000000000 --- a/docs/linking_to_external_code/reloading_modules.md +++ /dev/null @@ -1,33 +0,0 @@ -## Reloading modules - -By default, a module in the cache will be reused without fetching or -re-compiling it. Sometimes this is not desirable and you can force deno to -refetch and recompile modules into the cache. You can invalidate your local -`DENO_DIR` cache using the `--reload` flag of the `deno cache` subcommand. It's -usage is described below: - -### To reload everything - -```bash -deno cache --reload my_module.ts -``` - -### To reload specific modules - -Sometimes we want to upgrade only some modules. You can control it by passing an -argument to a `--reload` flag. - -To reload all \$STD_VERSION standard modules: - -```bash -deno cache --reload=https://deno.land/std@$STD_VERSION my_module.ts -``` - -To reload specific modules (in this example - colors and file system copy) use a -comma to separate URLs. - -```bash -deno cache --reload=https://deno.land/std@$STD_VERSION/fs/copy.ts,https://deno.land/std@$STD_VERSION/fmt/colors.ts my_module.ts -``` - -<!-- Should this be part of examples? --> |