diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 4f58eb8b3..46e081875 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -563,6 +563,45 @@ When using a `package.json` file, dev dependencies can be added to the separate } ``` +### JSR packages in package.json + +You can depend on JSR packages directly from `package.json` using the `jsr:` +scheme, without needing a separate `deno.json`: + +```json title="package.json" +{ + "dependencies": { + "@std/path": "jsr:^1.0.9" + } +} +``` + +This works with `deno install` and brings JSR packages to any project that uses +`package.json` for dependency management. + +### Dependency overrides + +The `overrides` field in `package.json` lets you control transitive dependency +versions throughout your dependency tree. This is useful for applying security +patches, fixing version compatibility issues, or replacing packages: + +```json title="package.json" +{ + "dependencies": { + "express": "^4.18.0" + }, + "overrides": { + "cookie": "0.7.0", + "express": { + "qs": "6.13.0" + } + } +} +``` + +In this example, `cookie` is pinned globally to `0.7.0`, while `qs` is +overridden only when required by `express`. + ### Why does Deno not have a `devImports` field? To understand why Deno does not separate out dev dependencies in the package diff --git a/runtime/reference/cli/compile.md b/runtime/reference/cli/compile.md index 12fc5ec32..8e45fcc9f 100644 --- a/runtime/reference/cli/compile.md +++ b/runtime/reference/cli/compile.md @@ -136,6 +136,43 @@ import "./worker.ts"; deno compile main.ts ``` +## Self-Extracting Executables + +By default, compiled executables serve embedded files from an in-memory virtual +file system. The `--self-extracting` flag changes this behavior so that the +binary extracts all embedded files to disk on first run and uses real file +system operations at runtime. + +```shell +deno compile --self-extracting main.ts +``` + +This is useful for scenarios where code needs real files on disk, such as native +addons or native code that reads relative files. + +The extraction directory is chosen in order of preference: + +1. `/.fs//` (next to the compiled binary) +2. Platform data directory fallback: + - Linux: `$XDG_DATA_HOME//` or + `~/.local/share//` + - macOS: `~/Library/Application Support//` + - Windows: `%LOCALAPPDATA%\\` + +Files are only extracted once — subsequent runs reuse the extracted directory if +it already exists and the hash matches. + +### Trade-offs + +Self-extracting mode enables broader compatibility, but comes with some +trade-offs: + +- **Initial startup cost**: The first run takes longer due to file extraction. +- **Disk usage**: Extracted files take up additional space on disk. +- **Memory usage**: Higher memory usage since embedded content can no longer be + referenced as static data. +- **Tamper risk**: Users or other code can modify the extracted files on disk. + ## Code Signing ### macOS diff --git a/runtime/reference/cli/upgrade.md b/runtime/reference/cli/upgrade.md index 8e946ec74..76bd09ca9 100644 --- a/runtime/reference/cli/upgrade.md +++ b/runtime/reference/cli/upgrade.md @@ -63,6 +63,30 @@ $ deno upgrade --quiet This is useful for scripting environments or when you want cleaner output in CI pipelines. +## Cached downloads + +Downloaded Deno binaries are cached in `$DENO_DIR/dl/`. If you reinstall the +same version later, the cached archive is reused instead of re-downloading. For +canary builds, old entries are automatically removed, keeping only the 10 most +recent versions. + +## Checksum verification + +Use the `--checksum` flag to verify a downloaded binary against a known SHA-256 +hash. This protects against tampering in CI environments and security-sensitive +setups: + +```shell +$ deno upgrade --checksum= 2.7.0 +``` + +SHA-256 checksums are published as `.sha256sum` files alongside release archives +on GitHub: + +```shell +$ curl -sL https://github.com/denoland/deno/releases/download/v2.7.0/deno-x86_64-unknown-linux-gnu.zip.sha256sum +``` + ## Canary build By default, Deno will upgrade from the official GitHub releases. You can specify