move private repositories into modules file, rename to mention depend… (

#953) Co-authored-by: Marvin Hagemeister <marvin@deno.com>
denoland · Oct 7, 2024 · 232b054 · 232b054
1 parent a2c473e
commit 232b054
Show file tree

Hide file tree

Showing 19 changed files with 150 additions and 130 deletions.
diff --git a/runtime/_data.ts b/runtime/_data.ts
@@ -21,7 +21,7 @@ export const sidebar = [
       "/runtime/fundamentals/node/",
       "/runtime/fundamentals/security/",
       {
-        label: "Modules",
+        label: "Modules and dependencies",
         id: "/runtime/fundamentals/modules/",
       },
       "/runtime/fundamentals/configuration/",
@@ -171,7 +171,6 @@ export const sidebar = [
         label: "Deno & VS Code",
         id: "/runtime/reference/vscode/",
       },
-      "/runtime/reference/private_repositories/",
       {
         label: "Using JSX and React",
         id: "/runtime/reference/jsx/",

diff --git a/runtime/contributing/building_from_source.md b/runtime/contributing/building_from_source.md
@@ -7,7 +7,7 @@ oldUrl:
 
 Below are instructions on how to build Deno from source. If you just want to use
 Deno you can download a prebuilt executable (more information in the
-[`Getting Started`](../getting_started/installation.md) chapter).
+[`Getting Started`](/runtime/getting_started/installation/) chapter).
 
 ## Cloning the Repository
 

diff --git a/runtime/fundamentals/configuration.md b/runtime/fundamentals/configuration.md
@@ -76,7 +76,8 @@ import express from "express";
 const app = express();
 ```
 
-Read more about [module imports](./modules.md)
+Read more about
+[module imports and dependencies](/runtime/fundamentals/modules/)
 
 ### Custom path mappings
 
@@ -316,7 +317,8 @@ sharing code.
 
 :::
 
-See also [Configuring TypeScript in Deno](../reference/ts_config_migration.md).
+See also
+[Configuring TypeScript in Deno](/runtime/reference/ts_config_migration/).
 
 ## Unstable features
 

diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md
@@ -1,5 +1,5 @@
 ---
-title: "Using modules in Deno"
+title: "Modules and dependencies"
 oldUrl:
   - /runtime/manual/basics/modules/
   - /runtime/manual/basics/modules/integrity_checking/
@@ -16,6 +16,8 @@ oldUrl:
   - /runtime/manual/linking_to_external_code/reloading_modules
   - /runtime/fundamentals/esm.sh
   - /runtime/manual/basics/import_maps/
+  - /runtime/manual/advanced/private_repositories/
+  - /runtime/reference/private_repositories/
 ---
 
 Deno uses
@@ -139,6 +141,23 @@ $ deno add jsr:@luca/cases@1.0.0
 Add @luca/cases - jsr:@luca/cases@1.0.0
 ```
 
+Read more in [`deno add` reference](/runtime/reference/cli/add/).
+
+You can also remove dependencies using `deno remove`:
+
+```sh
+$ deno remove @luca/cases
+Remove @luca/cases
+```
+
+```json title="deno.json"
+{
+  "imports": {}
+}
+```
+
+Read more in [`deno remove` reference](/runtime/reference/cli/remove/).
+
 ## Package Versions
 
 It is possible to specify a version range for the package you are importing.
@@ -381,3 +400,95 @@ following in a Deno configuration file:
   }
 }
 ```
+
+## Private repositories
+
+:::note
+
+If you're looking for private npm registries and `.npmrc` support, visit the
+[npm support](/runtime/fundamentals/node/#private-registries) page.
+
+:::
+
+There may be 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 are
+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 _n_
+number of tokens delimited by a semi-colon (`;`) where each token is either:
+
+- a bearer token in the format of `{token}@{hostname[:port]}` or
+- basic auth data in the format of `{username}:{password}@{hostname[:port]}`
+
+For example, a single token for `deno.land` would look something like this:
+
+```sh
+DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land
+```
+
+or:
+
+```sh
+DENO_AUTH_TOKENS=username:password@deno.land
+```
+
+And multiple tokens would look like this:
+
+```sh
+DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land;f1e2d3c4b5a6@example.com:8080;username:password@deno.land
+```
+
+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}` or `Basic {base64EncodedData}`. 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 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_:
+
+![Personal access tokens settings on GitHub](./images/private-pat.png)
+
+You would then choose to _Generate new token_ and give your token a description
+and appropriate access:
+
+![Creating a new personal access token on GitHub](./images/private-github-new-token.png)
+
+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:
+
+![Display of newly created token on GitHub](./images/private-github-token-display.png)
+
+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/runtime/fundamentals/node.md b/runtime/fundamentals/node.md
@@ -664,7 +664,7 @@ To learn more about the test runner and how to configure it, check out the
 :::caution
 
 Not to be confused with
-[private repositories and modules](/runtime/reference/private_repositories/).
+[private repositories and modules](/runtime/fundamentals/modules/#private-repositories).
 
 :::
 

diff --git a/runtime/getting_started/installation.md b/runtime/getting_started/installation.md
@@ -175,7 +175,8 @@ To test your installation, run `deno --version`. If this prints the Deno version
 to the console the installation was successful.
 
 Use `deno help` to see help text documenting Deno's flags and usage. Get a
-detailed guide on the CLI [here](./command_line_interface.md).
+detailed guide on the CLI
+[here](/runtime/getting_started/command_line_interface/).
 
 ## Updating
 
@@ -204,4 +205,4 @@ deno upgrade --version 1.0.1
 ## Building from source
 
 Information about how to build from source can be found in the
-[`Contributing`](../contributing/building_from_source.md) chapter.
+[`Contributing`](/runtime/contributing/building_from_source/) chapter.
diff --git a/runtime/reference/cli/compiler.md b/runtime/reference/cli/compiler.md
@@ -6,14 +6,15 @@ command: compile
 
 ## Flags
 
-As with [`deno install`](./install.md), the runtime flags used to execute the
-script must be specified at compilation time. This includes permission flags.
+As with [`deno install`](/runtime/reference/cli/install/), the runtime flags
+used to execute the script must be specified at compilation time. This includes
+permission flags.
 
 ```sh
 deno compile --allow-read --allow-net jsr:@std/http@1.0.0/file-server
 ```
 
-[Script arguments](../../getting_started/command_line_interface.md#passing-script-arguments)
+[Script arguments](/runtime/getting_started/command_line_interface.md#passing-script-arguments)
 can be partially embedded.
 
 ```console

diff --git a/runtime/reference/cli/init.md b/runtime/reference/cli/init.md
@@ -116,7 +116,7 @@ Run these commands to get started
   deno -R test
 ```
 
-Your [`deno.json`](../../fundamentals/configuration.md) file will look like
+Your [`deno.json`](/runtime/fundamentals/configuration/) file will look like
 this:
 
 ```json

diff --git a/runtime/reference/cli/install.md b/runtime/reference/cli/install.md
@@ -131,7 +131,7 @@ The above command creates an executable called `file_server` that runs with
 network and read permissions and binds to port 8080.
 
 For good practice, use the
-[`import.meta.main`](../../tutorials/module_metadata.md) idiom to specify the
+[`import.meta.main`](/runtime/tutorials/module_metadata/) idiom to specify the
 entry point in an executable script.
 
 Example:

diff --git a/runtime/reference/cli/lsp.md b/runtime/reference/cli/lsp.md
@@ -12,7 +12,7 @@ IDEs with go-to-definition support and automatic code formatting.
 
 Starts the Deno language server. The language server is used by editors to
 provide features like intellisense, code formatting, and more. Read more about
-[integrating with the Deno LSP](../lsp_integration.md).
+[integrating with the Deno LSP](/runtime/reference/lsp_integration/).
 
 ## Description
 

diff --git a/runtime/reference/cli/task_runner.md b/runtime/reference/cli/task_runner.md
@@ -12,8 +12,8 @@ command: task
 specific to a codebase.
 
 To get started, define your commands in your codebase's
-[Deno configuration file](../../fundamentals/configuration.md) under a `"tasks"`
-key.
+[Deno configuration file](/runtime/fundamentals/configuration/) under a
+`"tasks"` key.
 
 For example:
 

diff --git a/runtime/reference/cli/unstable_flags.md b/runtime/reference/cli/unstable_flags.md
@@ -137,7 +137,8 @@ Sloppy imports will allow (but print warnings for) the following:
 - Import a directory path, and automatically use `index.js` or `index.ts` as the
   import for that directory
 
-[`deno compile`](./compiler.md) does not support sloppy imports.
+[`deno compile`](/runtime/reference/cli/compiler/) does not support sloppy
+imports.
 
 ## `--unstable-unsafe-proto`
 

diff --git a/runtime/reference/deno_namespace_apis.md b/runtime/reference/deno_namespace_apis.md
@@ -28,7 +28,7 @@ Refer to the links below for code examples of how to use the file system
 functions.
 
 - [Reading files in several different ways](/examples/reading-files)
-- [Reading files in streams](../tutorials/file_server.md)
+- [Reading files in streams](/runtime/tutorials/file_server/)
 - [Reading a text file (`Deno.readTextFile`)](/examples/reading-files)
 - [Writing a text file (`Deno.writeTextFile`)](/examples/writing-files)
 
@@ -49,7 +49,7 @@ The Deno runtime comes with
 
 Refer to the links below for code samples of how to create a subprocess.
 
-- [Creating a subprocess (`Deno.Command`)](../tutorials/subprocess.md)
+- [Creating a subprocess (`Deno.Command`)](/runtime/tutorials/subprocess/)
 
 ## Errors
 

diff --git a/runtime/reference/lsp_integration.md b/runtime/reference/lsp_integration.md
@@ -19,8 +19,8 @@ visit
 The Deno CLI comes with a built in language server that can provide an
 intelligent editing experience, as well as a way to easily access the other
 tools that come built in with Deno. For most users, using the language server
-would be via an editor such as [Visual Studio Code](./vscode.md) or
-[other editors](/runtime/getting_started/setup_your_environment/).
+would be via an editor such as [Visual Studio Code](/runtime/reference/vscode/)
+or [other editors](/runtime/getting_started/setup_your_environment/).
 
 This page is designed for those creating integrations to the language server or
 providing a package registry for Deno that integrates intelligently.

diff --git a/runtime/reference/private_repositories.md b/runtime/reference/private_repositories.md
-Original file line number
+Diff line change
@@ Expand Up / @@ -116,7 +116,7 @@ Run these commands to get started @@
       deno -R test
     ```
-    Your [`deno.json`](../../fundamentals/configuration.md) file will look like
+    Your [`deno.json`](/runtime/fundamentals/configuration/) file will look like
     this:
     ```json
@@ Expand Down @@