chore: docs updates

website/docs/api-reference/configuration.md

@@ -10,20 +10,13 @@ Lerna's configuration is split into two files: `lerna.json` and `nx.json`.
 
 # Lerna.json
 
-### useWorkspaces & packages
+### npmClient
 
-Since Lerna was created, all major package managers (npm, yarn, and pnpm) have added the ability to cross-link packages
-in the same repo and dedupe node modules. If you'd like Lerna to delegate this process to the package manager you use,
-set `useWorkspaces: true` in `lerna.json`.
+It is important to set this value if you are not using `npm` as your package manager (e.g. if you are using `yarn` or `pnpm`) so that lerna can adjust some of its internal logic when resolving configuration and packages. This is particularly true in the case of `pnpm` because it uses a separate `pnpm-workspaces.yaml` file to define its workspaces configuration.
 
-```json title="lerna.json"
-{
-  "useWorkspaces": true
-}
-```
+### packages
 
-If you don't have `useWorkspaces` set to true, you need to set the `packages` property which will tell Lerna where to
-look for `package.json` files.
+By default, lerna will try and reuse any `workspaces` configuration you may have from your package manager of choice. If you prefer to specify a subset of your available packages for lerna to operate on, you can use the `packages` property which will tell Lerna where to look for `package.json` files.
 
 ```json title="lerna.json"
 {
@@ -33,8 +26,7 @@ look for `package.json` files.
 
 ### version
 
-Lerna has two modes of publishing packages: `fixed` and `independent`. When using the fixed mode, all the packages will
-be published using the same version. The last published version is recorded in `lerna.json` as follows:
+Lerna has two modes of publishing packages: `fixed` and `independent`. When using the fixed mode, all the affected packages will be published using the same version. The last published version is recorded in `lerna.json` as follows:
 
 ```json title="lerna.json"
 {
@@ -50,9 +42,11 @@ When using the independent mode, every package is versioned separately, and `ler
 }
 ```
 
+See the [version and publish docs](../features/version-and-publish.md) for more details.
+
 ### commands
 
-The `lerna.json` files can also encode commands options, as follows:
+The `lerna.json` files can also encode options for each command like so:
 
 ```json
 {

website/docs/faq.md

@@ -24,6 +24,14 @@ NOTE: Because lerna itself predates the `workspaces` feature in package managers
 
 You can use the [`lerna create`](https://github.com/lerna/lerna/tree/main/libs/commands/create#readme) command to create new packages within your lerna repo.
 
+```sh
+lerna create <packageName>
+```
+
+See the [create docs](https://github.com/lerna/lerna/tree/main/libs/commands/create#readme) for more options.
+
+If you don't want to use `lerna create`, then you can still manually create a package by running `npm init` within a subdirectory of the `packages` folder and Lerna will automatically detect it.
+
 ### Existing packages
 
 You can use [`lerna import <package>`][import] to transfer an existing package
@@ -37,17 +45,9 @@ case you will need to have the repo you wish to link to on your file system.
 
 ## How do I retry publishing if `publish` fails?
 
-Sometimes, `lerna publish` does not work. Your network may have had a hiccup, you may have not been logged on to npm, etc.
-
-If the `lerna.json` has not yet been updated, simply try `lerna publish` again.
-
-If it has been updated, you can force re-publish. `lerna publish --force-publish $(ls packages/)`
-
-### Recovering from a network error
-
-In the case that some packages were successfully published and others were not, `lerna publish` may have left the repository in an inconsistent state with some changed files. To recover from this, reset any extraneous local changes from the failed run to get back to a clean working tree. Then, retry the same `lerna publish` command. Lerna will attempt to publish all of the packages again, but will recognize those that have already been published and skip over them with a warning.
+In the case that some packages were successfully published and others were not, lerna publish may have left the repository in an inconsistent state with some changed files. To recover from this, reset any extraneous local changes from the failed run to get back to a clean working tree. Then, retry the same lerna publish command. Lerna will attempt to publish all of the packages again, but will recognize those that have already been published and skip over them with a warning.
 
-If you used the `lerna publish` command without positional arguments to select a new version for the packages, then you can run `lerna publish from-git` to retry publishing that same already-tagged version instead of having to bump the version again while retrying.
+If you used the lerna publish command without positional arguments to select a new version for the packages, then you can run lerna publish from-git to retry publishing that same already-tagged version instead of having to bump the version again while retrying.
 
 ## How does Lerna detect packages?
 

website/docs/features/version-and-publish.md

@@ -104,21 +104,31 @@ Successfully published:
 lerna success published 2 packages
 ```
 
+### from-package
+
+Another way Lerna can determine which packages to publish is with `from-package`. Lerna will compare the version of every package in the repository with the version of it that is published to npm. For each package that has a version that is greater than the published version, Lerna will publish that package to npm.
+
+This mode does not explicitly require that the packages have been versioned with `lerna version`, which makes it great for workspaces that have their own versioning scripts.
+
+```bash
+lerna publish from-package
+```
+
 ## Versioning strategies
 
 Lerna allows you to manage your project using one of two modes: Fixed or Independent.
 
 ### Fixed/Locked mode (default)
 
-Fixed mode Lerna projects operate on a single version line. The version is kept in the `lerna.json` file at the root of your project under the `version` key. When you run `lerna publish`, if a module has been updated since the last time a release was made, it will be updated to the new version you're releasing. This means that you only publish a new version of a package when you need to.
+Fixed mode Lerna projects operate on a single version line. The version is kept in the `lerna.json` file at the root of your project under the `version` key. When you run `lerna publish`, if a package has been updated since the last time a release was made, it will be updated to the new version you're releasing. This means that you only publish a new version of a package when you need to.
 
 > Note: If you have a major version zero, all updates are [considered breaking](https://semver.org/#spec-item-4). Because of that, running `lerna publish` with a major version zero and choosing any non-prerelease version number will cause new versions to be published for all packages, even if not all packages have changed since the last release.
 
 Use this if you want to automatically tie all package versions together. One issue with this approach is that a major change in any package will result in all packages having a new major version.
 
 #### Synchronized Versions
 
-Lerna will only version and publish packages that have changed since the previous release, causing package versions to drift apart over time. To prevent this, use the `--force-publish` option with `lerna version` and `lerna publish`. This will force Lerna to always version and publish all packages, regardless of if they have changed since the previous release. As a result, all package versions will stay synchronized to the version in `lerna.json`.
+Lerna will only version and publish packages that have changed since the previous release, causing package versions to drift apart over time. To prevent this, use the `--force-publish` option with `lerna version`. This will force Lerna to always version all packages, regardless of if they have changed since the previous release. Then they will all be published to the registry by `lerna publish from-git`. As a result, all package versions will stay synchronized to the version in `lerna.json`.
 
 ### Independent mode
 

website/docs/legacy-package-management.md

@@ -24,6 +24,54 @@ By using `workspaces`, your package manager will perform the same exact linking
 
 The same thing goes for replacing `lerna add`. Adding and removing dependencies is something your package manager already does for you, and because `workspaces` is a first class use case, you can run an appropriate `install` command to add a dependency to a specific package/workspace and, again, all the relevant local linking will take place automatically.
 
+See below for more concrete comparisons, and before and after usage.
+
+### Replacing your usage of `lerna bootstrap`/`lerna link`
+
+#### What does it do?
+
+`lerna bootstrap` was used in place of `npm install` (or `yarn`/`pnpm`). It would install all external packages and link all internal packages within the workspace. `lerna link` would just perform the internal linking step of this operation.
+
+#### Where would I find it?
+
+It would most likely be in the "scripts" property of `package.json` in the root of your workspace. Also check your CI pipelines, as they might also be calling `lerna bootstrap` in place of `npm install` (or `yarn`/`pnpm`).
+
+#### What do I replace it with?
+
+Replace `lerna bootstrap` with `npm install` (or `yarn`/`pnpm`). If you are already performing your package manager's install command somewhere in your workflow before where you had previously called `lerna bootstrap`, then you can just delete it instead. `lerna link` can just be removed, as the linking step is now handled by your package manager during `npm install`.
+
+### Replacing your usage of `lerna add`
+
+#### What does it do?
+
+`lerna add` was used to add a dependency to packages in the workspace. It would update the `package.json` files of each package to add the dependency.
+
+#### Where would I find it?
+
+Though usually called manually, `lerna add` might be found in some scripts in `package.json` in the root of your workspace.
+
+#### What do I replace it with?
+
+`lerna add` can mostly be replaced with a variation of `npm install` (or `yarn`/`pnpm`). The most common use case for `lerna add` was to add a single dependency to a single package within the workspace. This command looks like:
+
+```sh
+lerna add <dependency> --scope <package>
+```
+
+and can be replaced directly with:
+
+```sh
+npm install <dependency> -w <package>
+```
+
+The `-w` flag tells npm to only install the dependency in the workspace package specified by `<package>`, similar to the `--scope` option for Lerna.
+
+If you need to add a dependency to multiple packages, you can use the `-w` option multiple times:
+
+```sh
+npm install <dependency> -w <package1> -w <package2>
+```
+
 ### Custom Hoisting
 
 One of the nice things about lerna's legacy `bootstrap` command was the control it offered you around hoisting or not hoisting certain dependencies up to the root of the repo, or leaving them in nested locations.

website/docs/lerna-and-nx.md

@@ -6,9 +6,9 @@ type: explainer
 
 # Lerna and Nx
 
-Nrwl (the company behind the open source build system Nx) has taken over [stewardship of Lerna](https://dev.to/nrwl/lerna-is-dead-long-live-lerna-3jal). [Nx](https://nx.dev) is a build system developed by ex-Googlers and utilizes many of the techniques used by internal Google tools. Lerna v5 is the first release under this new stewardship, updating outdated packages and starting to do some cleanup on the repository itself. Starting with v5.1+, Lerna comes with the new possibility to integrate Nx and defer a lot of the task scheduling work to it.
+Nrwl (the company behind the open source build system Nx) has taken over [stewardship of Lerna](https://dev.to/nrwl/lerna-is-dead-long-live-lerna-3jal). [Nx](https://nx.dev) is a build system developed by ex-Googlers and utilizes many of the techniques used by internal Google tools. Lerna uses Nx to detect packages in the workspace and dependencies between them. Lerna defers to Nx's powerful task runner to run scripts, allowing you to run them in parallel, cache results, and distribute them across multiple machines, all while ensuring that dependencies between packages are respected.
 
-The following is a high level overview of what each tool provides. Note that all of the existing Lerna commands will continue to function as they have. Adding Nx or Nx Cloud simply improves what you're already doing.
+The following is a high level overview of what each tool provides. Lerna can continue to be used by itself, and adding Nx Cloud for free on top can dramatically improve what you're already doing.
 
 ## Lerna
 
@@ -48,7 +48,7 @@ Free and open source
 - Continue using Lerna as usual
 
 :::note
-When Lerna is running tasks with Nx and detects Nx target configuration, it will defer to Nx to detect task dependencies. Some options for `lerna run` will behave differently than older versions of Lerna. See [Using Lerna (Powered by Nx) to Run Tasks](docs/lerna6-obsolete-options.md) for more details.
+Lerna defers to Nx's power task runner behind the scenes to detect task dependencies. Some options for `lerna run` behave differently than in older versions of Lerna. See [Using Lerna (Powered by Nx) to Run Tasks](docs/lerna6-obsolete-options.md) for more details on what differs from older versions of Lerna.
 :::
 
 ---

website/docs/troubleshooting.md

@@ -120,6 +120,10 @@ You may also need to add the following to your `.npmrc` file on the individual p
 registry = https://[registry-url]
 ```
 
+:::info
+Lerna always uses `npm` tooling to publish packages, regardless of the `npmClient` set in the `lerna.json` file. This means that any `yarn` or `pnpm` configuration will not be detected. To ensure successful publishing to a private registry, make sure that `npm` is configured properly with environment variables or a `.npmrc` file.
+:::
+
 ## Jest / Visual Studio Code Debugging
 
 It is possible to debug [Jest](https://facebook.github.io/jest/) tests in a Lerna-managed package using [Visual Studio Code](https://code.visualstudio.com/). Debugging with breakpoints works with the vscode launch configuration below in the monorepo's `<root>/.vscode/launch.json` file. This example launches Jest for a single package `my-package` located in the monorepo.