docs: update docs for Yarn and pnpm built-in JSR support (#1029)

![image](https://github.com/user-attachments/assets/8d376a4a-7bf1-4894-a96d-5048777e440a)

![image](https://github.com/user-attachments/assets/0fd02ad4-6771-4be1-985b-4dad16e43fc8)

![image](https://github.com/user-attachments/assets/e5ae925d-1812-4d8d-add7-1edc12486560)

---------

Co-authored-by: Augustin Mauroy <[email protected]>
Co-authored-by: crowlkats <[email protected]>

Author: 3 people

api/src/docs.rs

@@ -88,6 +88,7 @@ lazy_static::lazy_static! {
           "alert-important",
           "alert-warning",
           "alert-caution",
+          "or-bar"
         ],
       )
       .link_rel(Some("nofollow"))
@@ -1215,44 +1216,44 @@ impl deno_doc::html::UsageComposer for DocUsageComposer {
 
     if !self.runtime_compat.deno.is_some_and(|compat| !compat) {
       map.insert(
-          UsageComposerEntry {
-            name: "Deno".to_string(),
-            icon: Some(
-              r#"<img src="/logos/deno.svg" alt="deno logo" draggable="false" />"#.into(),
-            ),
-          },
-          format!("Add Package\n```\ndeno add jsr:{scoped_name}\n```{import}\n---- OR ----\n\nImport directly with a jsr specifier\n{}\n", usage_to_md(&format!("jsr:{url}"), Some(self.package.as_str()))),
-        );
+        UsageComposerEntry {
+          name: "Deno".to_string(),
+          icon: Some(
+            r#"<img src="/logos/deno.svg" alt="deno logo" draggable="false" />"#.into(),
+          ),
+        },
+        format!("Add Package\n```\ndeno add jsr:{scoped_name}\n```{import}\n<div class='or-bar'>or</div>\n\nImport directly with a jsr specifier\n{}\n", usage_to_md(&format!("jsr:{url}"), Some(self.package.as_str()))),
+      );
     }
 
     if !self.runtime_compat.node.is_some_and(|compat| !compat) {
       map.insert(
-          UsageComposerEntry {
-            name: "npm".to_string(),
-            icon: Some(
-              r#"<img src="/logos/npm_textless.svg" alt="npm logo" draggable="false" />"#.into(),
-            ),
-          },
-          format!("Add Package\n```\nnpx jsr add {scoped_name}\n```{import}"),
-        );
+        UsageComposerEntry {
+          name: "pnpm".to_string(),
+          icon: Some(
+            r#"<img src="/logos/pnpm_textless.svg" alt="pnpm logo" draggable="false" />"#.into(),
+          ),
+        },
+        format!("Add Package\n```\npnpm i jsr:{scoped_name}\n```\n<div class='or-bar'>or (using pnpm 10.8 or older)</div>\n\n```\npnpm dlx jsr add {scoped_name}\n```{import}"),
+      );
       map.insert(
-          UsageComposerEntry {
-            name: "Yarn".to_string(),
-            icon: Some(
-              r#"<img src="/logos/yarn_textless.svg" alt="yarn logo" draggable="false" />"#.into(),
-            ),
-          },
-          format!("Add Package\n```\nyarn dlx jsr add {scoped_name}\n```{import}"),
-        );
+        UsageComposerEntry {
+          name: "Yarn".to_string(),
+          icon: Some(
+            r#"<img src="/logos/yarn_textless.svg" alt="yarn logo" draggable="false" />"#.into(),
+          ),
+        },
+        format!("Add Package\n```\nyarn add jsr:{scoped_name}\n```\n<div class='or-bar'>or (using Yarn 4.8 or older)</div>\n\n```\nyarn dlx jsr add {scoped_name}\n```{import}"),
+      );
       map.insert(
-          UsageComposerEntry {
-            name: "pnpm".to_string(),
-            icon: Some(
-              r#"<img src="/logos/pnpm_textless.svg" alt="pnpm logo" draggable="false" />"#.into(),
-            ),
-          },
-          format!("Add Package\n```\npnpm dlx jsr add {scoped_name}\n```{import}"),
-        );
+        UsageComposerEntry {
+          name: "npm".to_string(),
+          icon: Some(
+            r#"<img src="/logos/npm_textless.svg" alt="npm logo" draggable="false" />"#.into(),
+          ),
+        },
+        format!("Add Package\n```\nnpx jsr add {scoped_name}\n```{import}"),
+      );
     }
 
     if !self.runtime_compat.bun.is_some_and(|compat| !compat) {

frontend/docs/introduction.md

@@ -18,8 +18,14 @@ project.
 # deno
 deno add jsr:@luca/cases
 
-# npm (use any of npx, yarn dlx, pnpm dlx, or bunx)
-npx jsr add @luca/cases
+# pnpm 10.9+
+pnpm add jsr:@luca/cases
+
+# yarn 4.9+
+yarn add jsr:@luca/cases
+
+# npm, bun, and older versions of yarn or pnpm
+npx jsr add @luca/cases # replace npx with any of yarn dlx, pnpm dlx, or bunx
 ```
 
 After adding the package, you can import and use it in ES modules like so:

frontend/docs/npm-compatibility.md

@@ -19,7 +19,20 @@ downloaded from jsr.io and installed in your `node_modules` directory.
 
 ## Installing and using JSR packages
 
-You can add JSR packages to your project using the `jsr` CLI:
+If you are using a recent version of pnpm (10.9+) or Yarn (4.9+), you can
+install JSR packages using `pnpm install` or `yarn add` without any additional
+configuration. These versions of pnpm and Yarn both support JSR out of the box.
+
+```sh
+pnpm install jsr:@luca/cases
+```
+
+```sh
+yarn add jsr:@luca/cases
+```
+
+If you are using npm, an older version of pnpm or Yarn, or Bun, you can use the
+JSR CLI to install JSR packages:
 
 ```sh
 npx jsr add @luca/cases
@@ -28,13 +41,15 @@ npx jsr add @luca/cases
 This will add the `@luca/cases` package to your `package.json` file, and install
 it to your `node_modules` directory using your preferred package manager.
 
-The package manager to use will be automatically detected based on the presence
-of a `package.lock`, `yarn.lock` or `pnpm-lock.yaml` file in your project. You
-can also specify the package manager to use explicitly using the `--npm`,
-`--yarn`, or `--pnpm` flags to the `jsr add` command.
+When using the JSR CLI, the package manager to use will be automatically
+detected based on the presence of a `package.lock`, `yarn.lock` or
+`pnpm-lock.yaml` file in your project. You can also specify the package manager
+to use explicitly using the `--npm`, `--yarn`, or `--pnpm` flags to the
+`jsr add` command.
 
-> You should check the `.npmrc` file that is created into source control. This
-> enables future calls to `npm install` / `yarn` / `pnpm install` to succeed.
+> When using the JSR CLI, you should check the `.npmrc` file that is created
+> into source control. This enables future calls to `npm install` and alike to
+> succeed.
 
 You can then use the JSR package from your code:
 
@@ -72,9 +87,14 @@ you cannot publish packages to it. You can only use it to install jsr packages
 from npm.
 
 The `@jsr` npm scope is served from the JSR registry at `https://npm.jsr.io`.
-This means that you need to configure your package manager to use this registry
-to install JSR packages. When adding packages with the `jsr` CLI, this is done
-automatically.
+
+Recent versions of `yarn` and `pnpm` automatically configure pull packages in
+the `@jsr` scope from `https://npm.jsr.io`, so you don't need to do anything
+special to use JSR packages with these package managers.
+
+For other package managers, and older versions of `yarn` and `pnpm`, you need to
+configure your package manager to use the JSR registry to install JSR packages.
+When adding packages with the `jsr` CLI, this is done automatically.
 
 Instead of using the `jsr` CLI to install JSR packages, you can also manually
 configure your package manager to support installing JSR packages.

frontend/docs/using-packages.md

@@ -15,14 +15,16 @@ example below will add the most recent version of
 [`@luca/cases`](https://jsr.io/@luca/cases) to your project.
 
 ```bash
-# deno
+# deno, pnpm 10.9+, and yarn 4.9+ with first class JSR support
 deno add jsr:@luca/cases
+pnpm add jsr:@luca/cases
+yarn add jsr:@luca/cases
 
-# npm (one of the below, depending on your package manager)
+# npm, bun, and older versions of yarn or pnpm
 npx jsr add @luca/cases
+bunx jsr add @luca/cases
 yarn dlx jsr add @luca/cases
 pnpm dlx jsr add @luca/cases
-bunx jsr add @luca/cases
 ```
 
 If you're using Deno, the `deno add` command will add an
@@ -38,24 +40,41 @@ something like this:
 }
 ```
 
-For npm and npm-compatible package managers, the `jsr` command will add the
-dependency to your `package.json` file, along with a `.npmrc` file to your
-project root with the necessary config to use JSR with npm. Learn more about
+For npm compatible package managers, the dependency will be added to your
+`package.json` file, and the package will be installed to your `node_modules`
+directory.
+
+For npm, older versions of pnpm and Yarn, and for Bun, the `jsr` command will
+additionally add a `.npmrc` file to your project root with the necessary config
+to use JSR with npm. Learn more about
 [JSR's npm compatibility layer](/docs/npm-compatibility).
 
-After installation with `npx jsr add`, your package.json will contain a
-dependency entry that looks something like this:
+After installation with any npm compatible package manager, your package.json
+will contain a dependency entry that looks like one of these configurations:
+
+```json
+// pnpm 10.9+ and yarn 4.9+
+{
+  "dependencies": {
+    "@luca/cases": "jsr:@luca/cases@^1.0.1"
+  }
+}
+```
+
+or
 
 ```json
+// npm, bun, and older versions of yarn or pnpm
 {
   "dependencies": {
     "@luca/cases": "npm:@jsr/luca__cases@^1.0.1"
   }
 }
 ```
 
-This npm dependency configuration makes use of a special custom scope called
-`@jsr`, which is now configured for you in `.npmrc`:
+In npm, Bun, and older versions of yarn or pnpm the dependency configuration
+makes use of a special custom scope called `@jsr`, which is configured for you
+in `.npmrc`:
 
 ```
 @jsr:registry=https://npm.jsr.io
@@ -99,41 +118,49 @@ If you only care about the major version, you can specify just the major
 version:
 
 ```bash
-# deno
+# deno, pnpm 10.9+ and yarn 4.9+
 deno add jsr:@luca/cases@1
+pnpm add jsr:@luca/cases@1
+yarn add jsr:@luca/cases@1
 
-# npm (and npm-like systems)
+# npm (and bun, and older versions of yarn or pnpm)
 npx jsr add @luca/cases@1
 ```
 
 If you want to use a specific minor version, you can specify the minor version:
 
 ```bash
-# deno
+# deno, pnpm 10.9+ and yarn 4.9+
 deno add jsr:@luca/[email protected]
+pnpm add jsr:@luca/[email protected]
+yarn add jsr:@luca/[email protected]
 
-# npm (and npm-like systems)
+# npm (and bun, and older versions of yarn or pnpm)
 npx jsr add @luca/[email protected]
 ```
 
 If you want to use a specific patch version, you can specify the patch version:
 
 ```bash
-# deno
+# deno, pnpm 10.9+ and yarn 4.9+
 deno add jsr:@luca/[email protected]
+pnpm add jsr:@luca/[email protected]
+yarn add jsr:@luca/[email protected]
 
-# npm (and npm-like systems)
+# npm (and bun, and older versions of yarn or pnpm)
 npx jsr add @luca/[email protected]
 ```
 
 If you want to use at least a specific patch version, but do want to allow\
 updates, you can specify the patch version with a `^` prefix:
 
 ```bash
-# deno
+# deno, pnpm 10.9+ and yarn 4.9+
 deno add jsr:@luca/cases@^1.0.1
+pnpm add jsr:@luca/cases@^1.0.1
+yarn add jsr:@luca/cases@^1.0.1
 
-# npm (and npm-like systems)
+# npm (and bun, and older versions of yarn or pnpm)
 npx jsr add @luca/cases@^1.0.1
 ```
 

frontend/docs/with/cloudflare-workers.md

@@ -16,18 +16,28 @@ First, create a new Cloudflare Worker project:
 npm create cloudflare@latest
 yarn create cloudflare
 pnpm create cloudflare
+bun create cloudflare
 ```
 
-You can then add JSR packages with the `jsr` CLI. This will add the package to
-your `package.json` and install it into your `node_modules` folder using your
-preferred package manager (npm, yarn, or pnpm).
+You can then add JSR packages using your package manager. This will add the
+package to your `package.json` and install it into your `node_modules` folder
+using your preferred package manager (npm, yarn, or pnpm).
 
 ```shell
+# pnpm 10.9+ and yarn 4.9+
+pnpm add jsr:@std/encoding
+yarn add jsr:@std/encoding
+
+# npm, bun, and older versions of yarn or pnpm
 npx jsr add @std/encoding
+bunx jsr add @std/encoding
+yarn dlx jsr add @std/encoding
+pnpm dlx jsr add @std/encoding
 ```
 
-> Note: You should check the `.npmrc` file that is created into source control.
-> Without this, future calls to `npm install` / `yarn` / `pnpm install` will not
+> Note: A `.npmrc` file is created when using the JSR CLI. The `.npmrc` file
+> that is created should be checked into source control. Without this, future
+> calls to `npm install` / `yarn` / `pnpm install` / `bun install` will not
 > succeed.
 
 You can then import JSR packages in your code:

frontend/docs/with/nextjs.md

@@ -15,18 +15,28 @@ First, create a new Next.js project:
 npx create-next-app@latest
 yarn create next-app
 pnpm create next-app
+bun create next-app
 ```
 
-You can then add JSR packages with the `jsr` CLI. This will add the package to
-your `package.json` and install it into your `node_modules` folder using your
-preferred package manager (npm, yarn, or pnpm).
+You can then add JSR packages using your package manager. This will add the
+package to your `package.json` and install it into your `node_modules` folder
+using your preferred package manager (npm, yarn, or pnpm).
 
 ```shell
+# pnpm 10.9+ and yarn 4.9+
+pnpm add jsr:@std/encoding
+yarn add jsr:@std/encoding
+
+# npm, bun, and older versions of yarn or pnpm
 npx jsr add @std/encoding
+bunx jsr add @std/encoding
+yarn dlx jsr add @std/encoding
+pnpm dlx jsr add @std/encoding
 ```
 
-> Note: You should check the `.npmrc` file that is created into source control.
-> Without this, future calls to `npm install` / `yarn` / `pnpm install` will not
+> Note: A `.npmrc` file is created when using the JSR CLI. The `.npmrc` file
+> that is created should be checked into source control. Without this, future
+> calls to `npm install` / `yarn` / `pnpm install` / `bun install` will not
 > succeed.
 
 You can then import JSR packages in your code:

frontend/docs/with/node.md

@@ -12,16 +12,25 @@ JSR packages can be used in Node.js by using
 JSR packages are always ESM-only, so your project must be using
 `"type": "module"` in your `package.json` to use JSR packages.
 
-You can then add JSR packages with the `jsr` CLI. This will add the package to
-your `package.json` and install it into your `node_modules` folder using your
-preferred package manager (npm, yarn, or pnpm).
+You can then add JSR packages using your package manager. This will add the
+package to your `package.json` and install it into your `node_modules` folder
+using your preferred package manager (npm, yarn, or pnpm).
 
 ```shell
-npx jsr add @std/fmt
+# pnpm 10.9+ and yarn 4.9+
+pnpm add jsr:@std/encoding
+yarn add jsr:@std/encoding
+
+# npm, bun, and older versions of yarn or pnpm
+npx jsr add @std/encoding
+bunx jsr add @std/encoding
+yarn dlx jsr add @std/encoding
+pnpm dlx jsr add @std/encoding
 ```
 
-> Note: You should check the `.npmrc` file that is created into source control.
-> Without this, future calls to `npm install` / `yarn` / `pnpm install` will not
+> Note: A `.npmrc` file is created when using the JSR CLI. The `.npmrc` file
+> that is created should be checked into source control. Without this, future
+> calls to `npm install` / `yarn` / `pnpm install` / `bun install` will not
 > succeed.
 
 You can then import JSR packages in your code: