@microtronics/studio-cli 1.1.0-alpha.1 → 1.1.0-alpha.3

package/README.md

@@ -274,6 +274,27 @@ $ studio-cli usb sync -s 1234567890ABCDEF
 $ studio-cli usb sync -s 1234567890ABCDEF --debug
 ```
 
+## Library APM parts: version and dependencies
+
+Studio libraries (`type: "library"`) ship npm-consumable APM parts as `dist/blo/package.json` and
+`dist/pov/details/package.json`. `studio-cli` treats the library's `studio.json` as the single source of truth
+for both files:
+
+- **Version**: the `version` field in a library's own `blo/package.json` / `pov/details/package.json` source
+  files is irrelevant. `studio-cli build` (and therefore `pack`/`publish`) and `studio-cli install`/`i` both
+  stamp the `dist/<part>/package.json` `version` with the library's `studio.json` version.
+- **Dependencies**: other Studio libraries must be declared in `studio.json` `libraryDependencies` /
+  `libraryDevDependencies`, never as npm `peerDependencies`/`dependencies`/`optionalDependencies`. npm semver
+  ranges never match prereleases of a different major.minor (e.g. `^1.8.0` does not match `1.14.0-alpha.2`), and
+  Studio libraries are commonly consumed as prereleases. Any such entry found in a `dist/<part>/package.json` is
+  stripped, with a warning naming the removed entry and the file.
+
+Build time is authoritative for newly built/published libraries. Install time (via `studio-cli install`/`i`)
+additionally normalizes the whole installed dependency tree - every library reachable from the project's
+`libraryDependencies`/`libraryDevDependencies`, walked transitively through each library's own dependencies -
+which fixes libraries that were published before this normalization existed. A part `package.json` is patched
+in place, and each patch is logged as a warning so it is visible without `--debug`.
+
 ## Development
 
 Execute commands from the root dir