Document pub workspaces

firebase.json

@@ -181,7 +181,7 @@
       { "source": "/go/ffi", "destination": "/interop/c-interop", "type": 301 },
       { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 },
       { "source": "/go/macros", "destination": "/language/macros", "type": 301 },
-      { "source": "/go/pub-workspaces", "destination": "https://flutter.dev/go/pub-workspace", "type": 301 },
+      { "source": "/go/pub-workspaces", "destination": "/guides/packages#workspaces", "type": 301 },
       { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 },
       { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 },
       { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 },

src/content/guides/packages.md

@@ -261,6 +261,174 @@ To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`.
 
 [content hash]: /tools/pub/glossary#content-hashes
 
+<a name="workspaces"></a>
+## Pub Workspaces (Mono-repo Support)
+
+When working on a project, you might develop multiple Dart packages in the same
+version control repository (a mono-repo).
+
+For example you might have a directory layout like: 
+
+```console
+/
+  packages/
+    shared/
+      pubspec.yaml
+      pubspec.lock
+      .dart_tool/package_config.json
+    client_package/
+      pubspec.yaml
+      pubspec.lock
+      .dart_tool/package_config.json
+    server_package/
+      pubspec.yaml
+      pubspec.lock
+      .dart_tool/package_config.json
+```
+
+There are multiple issues with this organization:
+
+* You need to run `pub get` once for each package.
+* You risk ending up with different versions of dependencies for each package.
+  Leading to confusion when context switching between the packages.
+* If you open the root folder in your IDE, the dart analyzer will have to have a
+  separate analysis contexts for each package.
+
+Pub allows you to organize your repository as a "workspace" using a single
+shared resolution for all your packages.
+
+To create a workspace:
+
+* Add a `pubspec.yaml` at the repository root directory with a `workspace` entry
+  enummerating the paths to the packages of the respository (the workspace
+  packages):
+
+```yaml
+name: _
+environment:
+  sdk: ^3.6.0
+workspace:
+  - packages/helper
+  - packages/client_package
+  - packages/server_package
+```
+
+* For each of the existing `pubspec.yaml`s, make sure their sdk constraint is at
+  least `^3.6.0` and add a `resolution` entry:
+
+  ```yaml
+  environment:
+    sdk: ^3.6.0
+  resolution: workspace
+  ```
+
+* Run `dart pub get` anywhere in the repository, and this will:
+  * Create a single `pubspec.lock` next to the root `pubspec.yaml` that contains
+    the a resolution of all the `dependencies` and `dev_dependencies` of all the
+    workspace packages. 
+  * Create a single shared `.dart_tool/package_config.json` that maps package
+    names to file locations.
+  * Delete any other existing `pubspec.lock` and
+    `.dart_tool/package_config.json` files next to workspace packages.
+
+Now the file structure looks like this:
+
+```console
+/
+  packages/
+    shared/
+      pubspec.yaml
+    client_package/
+      pubspec.yaml
+    server_package/
+      pubspec.yaml
+  pubspec.yaml
+  pubspec.lock
+  .dart_tool/package_config.json
+```
+
+:::version-note
+Pub workspaces was introduced in Dart 3.6.0.
+
+To use pub workspaces, all your workspace packages (but not your dependencies)
+must have a sdk version constraint of `^3.6.0` or higher.
+:::
+
+### Interdependencies between workspace packages
+
+If any of the workspace packages depend on each other, they will automatically
+resolve to the one in the workspace, regardless of the source.
+
+Eg. `packages/client_package/pubspec.yaml` might depend on `shared`:
+
+```yaml
+dependencies:
+  shared: 
+    hosted: https://pub.dev
+    version: ^2.3.0
+```
+
+When resolved inside the workspace, the _local_ version of `shared` will be
+used. 
+
+The local version of `shared` would still have to match the constraint
+(`^2.3.0`) though.
+
+But when the package is consumed as a dependency without being part of the
+workspace, the original source (here `hosted`) is used.
+
+So if `client_package` is published to pub.dev and someone depends on it, they
+will get the hosted version of `shared` as a transitive dependency.
+
+### Dependency overrides in a workspace
+
+All `dependency_overrides:` sections in the workspace packages are respected,
+and you can also place a `pubspec_overrides.yaml` file next to any of the
+workspace `pubspec.yaml` files.
+
+You can only override a package once in the workspace.
+
+### Running a command in a specific workspace package
+
+Some pub commands, such as `dart pub add`, and `dart pub publish` operate on a
+"current" package. You can either change directory, or use `-C` to point pub at
+a directory:
+
+```console
+$ dart pub -C packages/client_package publish
+# Same as
+$ cd packages/client_package ; dart pub publish ; cd -
+```
+
+### Temporarily resolving a package outside its workspace:
+
+Sometimes you might want to resolve a workspace package on its own, eg. to
+validate its dependency constraints.
+
+One way to do this is to create a `pubspec_overides.yaml` file that resets the
+`resolution:` setting. Like:
+
+```yaml
+# packages/client_package/pubspec_overrides.yaml
+resolution:
+```
+
+Now running `pub get` inside `packages/client_package` will create an
+independent resolution.
+
+### Listing all workspace packages
+
+You can run `dart pub workspace list` to list the packages of a workspace.
+
+```console
+$ dart pub workspace list
+Package         Path                      
+_               ./                        
+client_package  packages/client_package/  
+server_package  packages/server_package/  
+shared          packages/shared/
+```
+
 ## More information
 
 The following pages have more information about packages and