Merge branch 'master' into feature/cc-31362/dev-click-and-collect-dev…

…eloper-overview

CODEOWNERS

@@ -7,6 +7,7 @@
 /docs/scos/dev/front-end-development/*/oryx/building-applications/styling/* @tobi-or-not-tobi @andriitserkovnyi @tolerants
 /docs/scos/dev/front-end-development/*/oryx/building-applications/styling/oryx-icon-system.md @supproduction @tobi-or-not-tobi @andriitserkovnyi
 /docs/scos/dev/front-end-development/*/oryx/building-applications/styling/oryx-design-tokens.md @tolerants @tobi-or-not-tobi @andriitserkovnyi
+/docs/scos/dev/front-end-development/*/oryx/getting-started/oryx-packages.md @tolerants @tobi-or-not-tobi @andriitserkovnyi
 /docs/scos/dev/set-up-spryker-locally/* @andriitserkovnyi
 /docs/pbc/all/dynamic-multistore/*/base-shop/dynamic-multistore-feature-overview.md @andriichekanov @a-sabaa
 /docs/pbc/all/warehouse-management-system/*/unified-commerce/ @andriispryker @andriitserkovnyi

docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md

@@ -1,29 +1,31 @@
 ---
 title: "Oryx: Packages"
 description: Use Oryx packages from npm to ensure you can easily upgrade to newer versions.
-last_updated: Apr 19, 2023
+last_updated: November 3, 2023
 template: concept-topic-template
 redirect_from:
   - /docs/scos/dev/front-end-development/202307.0/oryx/oryx-packages.html
 ---
 
+The Oryx code base is publicly [available on Github](https://github.com/spryker/oryx/) and the code is published on [npmjs.com](https://www.npmjs.com/). Npm is a widely used registry for npm packages, which is used by package managers, like npm, yarn, deno, or bun, to install dependencies in an application.
 
-
-The Oryx code base is [available on Github](https://github.com/spryker/oryx/), and the code is published and distributed as npm packages. [npmjs.com](https://www.npmjs.com/) is a widely used registry of packages. Package managers, like npm, yarn, deno, or bun, are used to install dependencies in a project. The dependencies are typically configured in the [package.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) file of an application.
+The dependencies are typically configured in the [package.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) file of an application.
 
 Oryx packages are distributed under the [spryker-oryx](https://www.npmjs.com/org/spryker-oryx) organization. Each time a new version is published, the version number is bumped. For more information on the versioning strategy, see [Versioning](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/oryx-versioning.html).
 
-We recommend [installing](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/set-up-oryx.html) the packages instead of cloning the Oryx repository. By depending on packages, you can easily upgrade to later versions of the packages.
+We recommend [installing](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/set-up-oryx.html) the packages rather than cloning the source code from the Oryx repository. By depending on packages, you can easily upgrade them to later versions.
+
+The Oryx framework relies on its own packages and third-party dependencies to provide a robust development experience. This document describes how Oryx manages these packages to ensure stability, security, and flexibility.
 
-## Layers
+## Oryx Packages
 
-While packages are distributed as a flat list, there is an architectural hierarchy. The hierarchy protects from cyclic dependencies. Packages inside a layer can depend on sibling packages inside the layer without any issues. Packages can never depend on a layer above.
+While packages are distributed as a flat list, there is an architectural hierarchy. The hierarchy protects from cyclic dependencies. Packages inside a layer can depend on sibling packages inside the layer without any issues. Packages never depend on a layer above.
 
 While the package layering might be irrelevant during your development, it might help you to better understand the package dependencies. The following diagram shows four package layers. The top layer is the [boilerplate application](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/oryx-boilerplate.html), which is set up using a [preset](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html).
 
 {% include diagrams/oryx/packages.md %}
 
-## Template packages
+### Template packages
 
 The template layer contains packages that can be used as quick starters for demos and projects. Templated packages follow semantic versioning and ensure upgradability. Some packages in the template layer, like presets, are opinionated and might not be used inside your final setup. Their main purpose is to quickly get up and running a standard frontend application.
 
@@ -42,7 +44,7 @@ The Labs package is an exception. It consists of experimental or demo functional
 
 {% endinfo_block %}
 
-## Domain packages
+### Domain packages
 
 Domain packages provide components and service logic for certain domains. Organizing packages in domains improves the developer experience by making it easy to understand where to find a certain component or service. For example, the `product` domain package contains all product-related components, as well as product services and adapters that integrate with Spryker APIs.
 
@@ -58,7 +60,7 @@ Domain packages provide components and service logic for certain domains. Organi
 | [Site](https://www.npmjs.com/package/@spryker-oryx/site)         | `@spryker-oryx/site`     |
 | [User](https://www.npmjs.com/package/@spryker-oryx/user)         | `@spryker-oryx/user`     |
 
-## Platform packages
+### Platform packages
 
 The platform layer contains the core packages of the Oryx framework. They provide the infrastructure to the whole system.
 
@@ -74,7 +76,7 @@ The platform layer contains the core packages of the Oryx framework. They provid
 | [Push-notification](https://www.npmjs.com/package/@spryker-oryx/push-notification) | `@spryker-oryx/push-notification` |
 | [Router](https://www.npmjs.com/package/@spryker-oryx/router)                       | `@spryker-oryx/router`            |
 
-## Base packages
+### Base packages
 
 The base layer contains packages that serve as utilities to all layers above. An important part of the base layer is the design system package (UI).
 
@@ -83,3 +85,25 @@ The base layer contains packages that serve as utilities to all layers above. An
 | [UI](https://www.npmjs.com/package/@spryker-oryx/ui)               | `@spryker-oryx/ui`        |
 | [Utilities](https://www.npmjs.com/package/@spryker-oryx/utilities) | `@spryker-oryx/utilities` |
 | [DI](https://www.npmjs.com/package/@spryker-oryx/di)               | `@spryker-oryx/di`        |
+
+## Managing third-party dependencies
+
+Oryx follows a careful approach when incorporating third-party components. Third-party components are included only when they bring significant value to projects. This approach involves minimizing unnecessary dependencies and thoroughly assessing their worth to prevent issues like outdated packages, vulnerabilities, and compatibility problems that may disrupt code stability.
+
+We conduct regular inspections of third-party components to check for updates and compatibility, identify and fix vulnerabilities. Attention is also given to optimizing bundle size and performance to maintain applications fast and responsive.
+
+To continue innovating and keep the ecosystem healthy, we follow the guidelines:
+
+- Avoid unnecessary third party dependencies: minimize the use of third-party dependencies to mitigate risks and maintain control over the ecosystem.
+
+- Evaluate dependencies carefully: before adding a new third-party dependency, we carefully evaluate its risks and benefits, considering factors such as maintenance, community support, security track record, and adherence to semantic versioning.
+
+- Use semantic versioning and caret (^) notation in `package.json`: this ensures compatibility and allows for seamless updates without introducing breaking changes. Ideally, versions only include the major version number, so that the minor and patch are controlled by application owners and can be updated over time. Example: `"lit": "^2.0.0"`.
+
+- Avoid shipping lock files in the boilerplate: Lock files, like `package-lock.json`, are not included in the Oryx boilerplate to let application developers benefit from the latest versions of dependencies when creating their projects.
+
+- Use peer dependencies: enables application owners to choose specific versions of dependencies while maintaining compatibility with the framework.
+
+- Document version resolutions: when known security concerns or significant improvements can only be solved with a breaking change to the dependencies, we add _version resolutions_ to the Oryx documentation. Application owners can change their `package.json` accordingly to override specific dependencies.
+
+By following these guidelines, Oryx aims to maintain a stable and secure ecosystem while providing flexibility for application developers to choose the versions of dependencies that suit their needs.

docs/scos/dev/front-end-development/202311.0/oryx/getting-started/oryx-packages.md

@@ -9,21 +9,25 @@ redirect_from:
 
 
 
-The Oryx code base is [available on Github](https://github.com/spryker/oryx/), and the code is published and distributed as npm packages. [npmjs.com](https://www.npmjs.com/) is a widely used registry of packages. Package managers, like npm, yarn, deno, or bun, are used to install dependencies in a project. The dependencies are typically configured in the [package.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) file of an application.
+The Oryx code base is publicly [available on Github](https://github.com/spryker/oryx/) and the code is published on [npmjs.com](https://www.npmjs.com/). Npm is a widely used registry for npm packages, which is used by package managers, like npm, yarn, deno, or bun, to install dependencies in an application.
+
+The dependencies are typically configured in the [package.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) file of an application.
 
 Oryx packages are distributed under the [spryker-oryx](https://www.npmjs.com/org/spryker-oryx) organization. Each time a new version is published, the version number is bumped. For more information on the versioning strategy, see [Versioning](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/oryx-versioning.html).
 
-We recommend [installing](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/set-up-oryx.html) the packages instead of cloning the Oryx repository. By depending on packages, you can easily upgrade to later versions of the packages.
+We recommend [installing](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/set-up-oryx.html) the packages rather than cloning the source code from the Oryx repository. By depending on packages, you can easily upgrade them to later versions.
+
+The Oryx framework relies on its own packages and third-party dependencies to provide a robust development experience. This document describes how Oryx manages these packages to ensure stability, security, and flexibility.
 
-## Layers
+## Oryx Packages
 
-While packages are distributed as a flat list, there is an architectural hierarchy. The hierarchy protects from cyclic dependencies. Packages inside a layer can depend on sibling packages inside the layer without any issues. Packages can never depend on a layer above.
+While packages are distributed as a flat list, there is an architectural hierarchy. The hierarchy protects from cyclic dependencies. Packages inside a layer can depend on sibling packages inside the layer without any issues. Packages never depend on a layer above.
 
 While the package layering might be irrelevant during your development, it might help you to better understand the package dependencies. The following diagram shows four package layers. The top layer is the [boilerplate application](/docs/scos/dev/front-end-development/{{page.version}}/oryx/getting-started/oryx-boilerplate.html), which is set up using a [preset](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html).
 
 {% include diagrams/oryx/packages.md %}
 
-## Template packages
+### Template packages
 
 The template layer contains packages that can be used as quick starters for demos and projects. Templated packages follow semantic versioning and ensure upgradability. Some packages in the template layer, like presets, are opinionated and might not be used inside your final setup. Their main purpose is to quickly get up and running a standard frontend application.
 
@@ -32,8 +36,8 @@ The template layer contains packages that can be used as quick starters for demo
 |                                                                        |                             |
 | [Application](https://www.npmjs.com/package/@spryker-oryx/application) | `@spryker-oryx/application` |
 | [Presets](https://www.npmjs.com/package/@spryker-oryx/presets)         | `@spryker-oryx/presets`     |
-| [Labs](https://www.npmjs.com/package/@spryker-oryx/labs)               | `@spryker-oryx/labs`        |
-| [Themes](https://www.npmjs.com/package/@spryker-oryx/themes)           | `@spryker-oryx/themes`      |
+| [Labs ](https://www.npmjs.com/package/@spryker-oryx/labs)              | `@spryker-oryx/labs`        |
+| [Themes ](https://www.npmjs.com/package/@spryker-oryx/themes)          | `@spryker-oryx/themes`      |
 | [Resources](https://www.npmjs.com/package/@spryker-oryx/resources)     | `@spryker-oryx/resources`   |
 
 {% info_block infoBox %}
@@ -42,7 +46,7 @@ The Labs package is an exception. It consists of experimental or demo functional
 
 {% endinfo_block %}
 
-## Domain packages
+### Domain packages
 
 Domain packages provide components and service logic for certain domains. Organizing packages in domains improves the developer experience by making it easy to understand where to find a certain component or service. For example, the `product` domain package contains all product-related components, as well as product services and adapters that integrate with Spryker APIs.
 
@@ -58,7 +62,7 @@ Domain packages provide components and service logic for certain domains. Organi
 | [Site](https://www.npmjs.com/package/@spryker-oryx/site)         | `@spryker-oryx/site`     |
 | [User](https://www.npmjs.com/package/@spryker-oryx/user)         | `@spryker-oryx/user`     |
 
-## Platform packages
+### Platform packages
 
 The platform layer contains the core packages of the Oryx framework. They provide the infrastructure to the whole system.
 
@@ -74,7 +78,7 @@ The platform layer contains the core packages of the Oryx framework. They provid
 | [Push-notification](https://www.npmjs.com/package/@spryker-oryx/push-notification) | `@spryker-oryx/push-notification` |
 | [Router](https://www.npmjs.com/package/@spryker-oryx/router)                       | `@spryker-oryx/router`            |
 
-## Base packages
+### Base packages
 
 The base layer contains packages that serve as utilities to all layers above. An important part of the base layer is the design system package (UI).
 
@@ -83,3 +87,25 @@ The base layer contains packages that serve as utilities to all layers above. An
 | [UI](https://www.npmjs.com/package/@spryker-oryx/ui)               | `@spryker-oryx/ui`        |
 | [Utilities](https://www.npmjs.com/package/@spryker-oryx/utilities) | `@spryker-oryx/utilities` |
 | [DI](https://www.npmjs.com/package/@spryker-oryx/di)               | `@spryker-oryx/di`        |
+
+## Managing third-party dependencies
+
+Oryx follows a careful approach when incorporating third-party components. Third-party components are included only when they bring significant value to projects. This approach involves minimizing unnecessary dependencies and thoroughly assessing their worth to prevent issues like outdated packages, vulnerabilities, and compatibility problems that may disrupt code stability.
+
+We conduct regular inspections of third-party components to check for updates and compatibility, identify and fix vulnerabilities. Attention is also given to optimizing bundle size and performance to maintain applications fast and responsive.
+
+To continue innovating and keep the ecosystem healthy, we follow the guidelines:
+
+- Avoid unnecessary third party dependencies: minimize the use of third-party dependencies to mitigate risks and maintain control over the ecosystem.
+
+- Evaluate dependencies carefully: before adding a new third-party dependency, we carefully evaluate its risks and benefits, considering factors such as maintenance, community support, security track record, and adherence to semantic versioning.
+
+- Use semantic versioning and caret (^) notation in `package.json`: this ensures compatibility and allows for seamless updates without introducing breaking changes. Ideally, versions only include the major version number, so that the minor and patch are controlled by application owners and can be updated over time. Example: `"lit": "^2.0.0"`.
+
+- Avoid shipping lock files in the boilerplate: Lock files, like `package-lock.json`, are not included in the Oryx boilerplate to let application developers benefit from the latest versions of dependencies when creating their projects.
+
+- Use peer dependencies: enables application owners to choose specific versions of dependencies while maintaining compatibility with the framework.
+
+- Document version resolutions: when known security concerns or significant improvements can only be solved with a breaking change to the dependencies, we add _version resolutions_ to the Oryx documentation. Application owners can change their `package.json` accordingly to override specific dependencies.
+
+By following these guidelines, Oryx aims to maintain a stable and secure ecosystem while providing flexibility for application developers to choose the versions of dependencies that suit their needs.