docs: add peer dep explainer (#876)

Adds a blurb out peer deps and lib development, installation.

@beeme1mr I also added a bit about `--legacy-peer-deps` after the
closure of #834

---------

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

packages/client/README.md

@@ -36,7 +36,7 @@
 </p>
 <!-- x-hide-in-docs-start -->
 
-[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
+[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool or in-house solution.
 
 <!-- x-hide-in-docs-end -->
 
@@ -61,6 +61,11 @@ npm install --save @openfeature/web-sdk
 yarn add @openfeature/web-sdk @openfeature/core
 ```
 
+> [!NOTE]  
+> `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations.
+> Every SDK version has a requirement on a single, specific version of this dependency.
+> For more information, and similar implications on libraries developed with OpenFeature see [considerations when extending](#considerations).
+
 ### Usage
 
 ```ts
@@ -336,3 +341,11 @@ export class MyHook implements Hook {
 ```
 
 > Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs!
+
+### Considerations
+
+When developing a library based on OpenFeature components, it's important to list the `@openfeature/web-sdk` as a `peerDependency` of your package.
+This is a general best-practice when developing JavaScript libraries that have dependencies in common with their consuming application.
+Failing to do this can result in multiple copies of the OpenFeature SDK in the consumer, which can lead to type errors, and broken singleton behavior.
+The `@openfeature/core` package itself follows this pattern: the `@openfeature/web-sdk` has a peer dependency on `@openfeature/core`, and uses whatever copy of that module the consumer has installed (note that NPM installs peers automatically unless `--legacy-peer-deps` is set, while yarn does not, and PNPM does so based on its configuration).
+When developing such libraries, it's NOT necessary to add a `peerDependency` on `@openfeature/core`, since the `@openfeature/web-sdk` establishes that dependency itself transitively.

packages/server/README.md

@@ -36,7 +36,7 @@
 </p>
 <!-- x-hide-in-docs-start -->
 
-[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
+[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool or in-house solution.
 
 <!-- x-hide-in-docs-end -->
 
@@ -61,6 +61,11 @@ npm install --save @openfeature/server-sdk
 yarn add @openfeature/server-sdk @openfeature/core
 ```
 
+> [!NOTE]  
+> `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations.
+> Every SDK version has a requirement on a single, specific version of this dependency.
+> For more information, and similar implications on libraries developed with OpenFeature see [considerations when extending](#considerations).
+
 ### Usage
 
 ```ts
@@ -362,3 +367,11 @@ export class MyHook implements Hook {
 ```
 
 > Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs!
+
+### Considerations
+
+When developing a library based on OpenFeature components, it's important to list the `@openfeature/server-sdk` as a `peerDependency` of your package.
+This is a general best-practice when developing JavaScript libraries that have dependencies in common with their consuming application.
+Failing to do this can result in multiple copies of the OpenFeature SDK in the consumer, which can lead to type errors, and broken singleton behavior.
+The `@openfeature/core` package itself follows this pattern: the `@openfeature/server-sdk` has a peer dependency on `@openfeature/core`, and uses whatever copy of that module the consumer has installed (note that NPM installs peers automatically unless `--legacy-peer-deps` is set, while yarn does not, and PNPM does so based on its configuration).
+When developing such libraries, it's NOT necessary to add a `peerDependency` on `@openfeature/core`, since the `@openfeature/server-sdk` establishes that dependency itself transitively.