diff --git a/docs/linking_to_external_code.md b/docs/linking_to_external_code.md index e03bfdfee8..1ec5564787 100644 --- a/docs/linking_to_external_code.md +++ b/docs/linking_to_external_code.md @@ -41,26 +41,10 @@ default directory is: ## FAQ -### But what if `https://deno.land/` goes down? +### How do I import a specific version of a module? -Relying on external servers is convenient for development but brittle in -production. Production software should always bundle its dependencies. In Deno -this is done by checking the `$DENO_DIR` into your source control system, and -specifying that path as the `$DENO_DIR` environmental variable at runtime. - -### How can I trust a URL that may change? - -By using a lock file (using the `--lock` command line flag) you can ensure -you're running the code you expect to be. You can learn more about this -[here](./linking_to_external_code/integrity_checking.md). - -### How do you import to a specific version? - -Simply specify the version in the URL. For example, this URL fully specifies the -code being run: `https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with -the aforementioned technique of setting `$DENO_DIR` in production to stored -code, one can fully specify the exact code being run, and execute the code -without network access. +Specify the version in the URL. For example, this URL fully specifies the code +being run: `https://unpkg.com/liltest@0.0.5/dist/liltest.js`. ### It seems unwieldy to import URLs everywhere. @@ -91,3 +75,31 @@ import { assertEquals, runTests, test } from "./deps.ts"; This design circumvents a plethora of complexity spawned by package management software, centralized code repositories, and superfluous file formats. + +### How can I trust a URL that may change? + +By using a lock file (with the `--lock` command line flag), you can ensure that +the code pulled from a URL is the same as it was during initial development. You +can learn more about this +[here](./linking_to_external_code/integrity_checking.md). + +### But what if the host of the URL goes down? The source won't be available. + +This, like the above, is a problem faced by _any_ remote dependency system. +Relying on external servers is convenient for development but brittle in +production. Production software should always vendor its dependencies. In Node +this is done by checking `node_modules` into source control. In Deno this is +done by pointing `$DENO_DIR` to some project-local directory at runtime, and +similarly checking that into source control: + +```shell +# Download the dependencies. +DENO_DIR=./deno_dir deno cache src/deps.ts + +# Make sure the variable is set for any command which invokes the cache. +DENO_DIR=./deno_dir deno test src + +# Check the directory into source control. +git add -u deno_dir +git commit +``` diff --git a/docs/linking_to_external_code/integrity_checking.md b/docs/linking_to_external_code/integrity_checking.md index 820ea1d2b8..91d595cdaf 100644 --- a/docs/linking_to_external_code/integrity_checking.md +++ b/docs/linking_to_external_code/integrity_checking.md @@ -1,5 +1,33 @@ ## Integrity checking & lock files -Deno can store and check module 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`. +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`. + +A typical workflow will look like this: + +```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"; +``` + +```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 -r --lock=lock.json src/deps.ts + +# Done! You can proceed safely. +deno test --allow-read src +```