From 3d329b54f5ec9caa7172b0afbecfd6cb6bb4345a Mon Sep 17 00:00:00 2001
From: tobi-or-not-tobi <tobi-or-not-tobi@users.noreply.github.com>
Date: Fri, 3 Nov 2023 08:31:14 +0100
Subject: [PATCH 1/6] Add 3rd party docs
---
.../oryx/getting-started/oryx-packages.md | 38 ++++++++++++++-----
1 file changed, 29 insertions(+), 9 deletions(-)
diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
index 14eb7bc13db..730114333ec 100644
--- a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
+++ b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
@@ -1,21 +1,23 @@
---
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 published and distributed on [npmjs.com](https://www.npmjs.com/). Npm is a widely used registry of npm packages, that 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.
+It is highly recommended to [install](/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 to later versions of the packages.
+
+The Oryx framework utilizes both its own packages and third party dependencies to provide a robust development experience. In this document, we will explore 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.
@@ -23,7 +25,7 @@ While the package layering might be irrelevant during your development, it might
{% 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.
@@ -41,7 +43,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.
@@ -57,7 +59,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.
@@ -73,7 +75,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).
@@ -82,3 +84,21 @@ 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 it comes to incorporating third party dependencies. By minimizing unnecessary dependencies and evaluating them based on various factors, Oryx aims to avoid potential issues such as outdated packages, vulnerabilities, and compatibility problems that could introduce breaking changes. Here are some guidelines we follow:
+
+- **Avoid unnecessary third party dependencies**: We strive to minimize the use of third party dependencies whenever possible 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**: We prefer to use semantic versioning and the caret (^) notation in the `package.json` file to ensure compatibility and allow 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. E.g. `"lit": "^2.0.0"`.
+
+- **Avoid shipping lock files in the boilerplate**: Lock files, such as `package-lock.json`, are not included in the Oryx boilerplate to allow application developers to benefit from the latest versions of dependencies when creating their projects.
+
+- **Utilize peer dependencies**: Oryx makes use of peer dependencies whenever possible, allowing application owners to choose specific versions of dependencies while maintaining compatibility with the framework.
+
+- **Documented version resolutions**: In cases where there are known security concerns or significant improvements, Oryx may document version resolutions for the `package.json` file for application owners to override specific dependency versions.
+
+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 best suit their needs.
From 92455b3248f752a172a2b0c717d342a4173928c2 Mon Sep 17 00:00:00 2001
From: tobi-or-not-tobi <tobi-or-not-tobi@users.noreply.github.com>
Date: Mon, 6 Nov 2023 07:18:08 +0100
Subject: [PATCH 2/6] fixes
---
.../202307.0/oryx/getting-started/oryx-packages.md | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
index 730114333ec..b63a0bea710 100644
--- a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
+++ b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
@@ -7,7 +7,7 @@ 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 published and distributed on [npmjs.com](https://www.npmjs.com/). Npm is a widely used registry of npm packages, that is used by package managers, like npm, yarn, deno, or bun, to install dependencies in 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, that 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.
@@ -87,7 +87,11 @@ The base layer contains packages that serve as utilities to all layers above. An
## Managing Third Party Dependencies
-Oryx follows a careful approach when it comes to incorporating third party dependencies. By minimizing unnecessary dependencies and evaluating them based on various factors, Oryx aims to avoid potential issues such as outdated packages, vulnerabilities, and compatibility problems that could introduce breaking changes. Here are some guidelines we follow:
+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 could disrupt code stability.
+
+To demonstrate commitment to code quality and security, regular inspections of third-party components are conducted to identify and fix vulnerabilities. Attention is also given to optimizing bundle size and performance to maintain fast and responsive applications. Prioritizing the well-being of dependencies includes regular checks for updates and compatibility to maintain a strong and well-maintained ecosystem.
+
+The following guidelines are used to ensure Oryx can continue to innovate and maintained:
- **Avoid unnecessary third party dependencies**: We strive to minimize the use of third party dependencies whenever possible to mitigate risks and maintain control over the ecosystem.
@@ -99,6 +103,6 @@ Oryx follows a careful approach when it comes to incorporating third party depen
- **Utilize peer dependencies**: Oryx makes use of peer dependencies whenever possible, allowing application owners to choose specific versions of dependencies while maintaining compatibility with the framework.
-- **Documented version resolutions**: In cases where there are known security concerns or significant improvements, Oryx may document version resolutions for the `package.json` file for application owners to override specific dependency versions.
+- **Document version resolutions**: In cases where there are known security concerns or significant improvements that can only be solved with a breaking change to the dependencies, a _version resolutions_ might be added 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 best suit their needs.
From f0e3e4ff48f25dd84bfa92faf852c9771140b31a Mon Sep 17 00:00:00 2001
From: Andrii Tserkovnyi <andrii.tserkovnyi@spryker.com>
Date: Wed, 6 Dec 2023 10:48:15 +0200
Subject: [PATCH 3/6] Update oryx-packages.md
---
.../oryx/getting-started/oryx-packages.md | 22 +++++++++----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
index b63a0bea710..93fc8293128 100644
--- a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
+++ b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
@@ -7,19 +7,19 @@ 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, that is used by package managers, like npm, yarn, deno, or bun, to install dependencies in 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).
-It is highly recommended to [install](/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 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 to later versions of the packages.
-The Oryx framework utilizes both its own packages and third party dependencies to provide a robust development experience. In this document, we will explore how Oryx manages these packages to ensure stability, security, and flexibility.
+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.
## 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).
@@ -85,19 +85,19 @@ The base layer contains packages that serve as utilities to all layers above. An
| [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
+## 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 could disrupt code stability.
+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.
-To demonstrate commitment to code quality and security, regular inspections of third-party components are conducted to identify and fix vulnerabilities. Attention is also given to optimizing bundle size and performance to maintain fast and responsive applications. Prioritizing the well-being of dependencies includes regular checks for updates and compatibility to maintain a strong and well-maintained ecosystem.
+We conduct regular inspections of third-party components to identify and fix vulnerabilities. Attention is also given to optimizing bundle size and performance to maintain fast and responsive applications. Prioritizing the well-being of dependencies includes regular checks for updates and compatibility to maintain a strong and well-maintained ecosystem.
-The following guidelines are used to ensure Oryx can continue to innovate and maintained:
+To continue innovating and keeping a well-maintained ecosystem, we follow the guidelines:
-- **Avoid unnecessary third party dependencies**: We strive to minimize the use of third party dependencies whenever possible to mitigate risks and maintain control over the ecosystem.
+- 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.
+- 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**: We prefer to use semantic versioning and the caret (^) notation in the `package.json` file to ensure compatibility and allow 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. E.g. `"lit": "^2.0.0"`.
+- Use semantic versioning and caret (^) notation: we prefer to use semantic versioning and the caret notation in `package.json` to ensure compatibility and allow 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. E.g. `"lit": "^2.0.0"`.
- **Avoid shipping lock files in the boilerplate**: Lock files, such as `package-lock.json`, are not included in the Oryx boilerplate to allow application developers to benefit from the latest versions of dependencies when creating their projects.
From 32c254cf1b2234c959e6239a3195b070870a7207 Mon Sep 17 00:00:00 2001
From: Andrii Tserkovnyi <andrii.tserkovnyi@spryker.com>
Date: Wed, 6 Dec 2023 11:37:21 +0200
Subject: [PATCH 4/6] Update oryx-packages.md
---
.../oryx/getting-started/oryx-packages.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
index 93fc8293128..4383b5ebe3a 100644
--- a/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
+++ b/docs/scos/dev/front-end-development/202307.0/oryx/getting-started/oryx-packages.md
@@ -13,7 +13,7 @@ The dependencies are typically configured in the [package.json](https://docs.npm
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 rather than cloning the source code from 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.
@@ -89,20 +89,20 @@ The base layer contains packages that serve as utilities to all layers above. An
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 identify and fix vulnerabilities. Attention is also given to optimizing bundle size and performance to maintain fast and responsive applications. Prioritizing the well-being of dependencies includes regular checks for updates and compatibility to maintain a strong and well-maintained ecosystem.
+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 keeping a well-maintained ecosystem, we follow the guidelines:
+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: we prefer to use semantic versioning and the caret notation in `package.json` to ensure compatibility and allow 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. E.g. `"lit": "^2.0.0"`.
+- 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, such as `package-lock.json`, are not included in the Oryx boilerplate to allow application developers to benefit from the latest versions of dependencies when creating their projects.
+- 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.
-- **Utilize peer dependencies**: Oryx makes use of peer dependencies whenever possible, allowing application owners to choose specific versions of dependencies while maintaining compatibility with the framework.
+- Use peer dependencies: enables application owners to choose specific versions of dependencies while maintaining compatibility with the framework.
-- **Document version resolutions**: In cases where there are known security concerns or significant improvements that can only be solved with a breaking change to the dependencies, a _version resolutions_ might be added to the Oryx documentation. Application owners can change their `package.json` accordingly to override specific dependencies.
+- 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 best suit their needs.
+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.
From 457fec1a0850fb287eac69ef1d2c7223429e9070 Mon Sep 17 00:00:00 2001
From: Andrii Tserkovnyi <andrii.tserkovnyi@spryker.com>
Date: Wed, 6 Dec 2023 11:38:55 +0200
Subject: [PATCH 5/6] Update CODEOWNERS
---
CODEOWNERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/CODEOWNERS b/CODEOWNERS
index 8b567385155..54cfad58845 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -7,6 +7,7 @@ docs/scos/dev/front-end-development/*/oryx/building-applications/oryx-localizati
/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
From 7e90e0042a153d86b061d927ca7753ddf1e4f625 Mon Sep 17 00:00:00 2001
From: Andrii Tserkovnyi <andrii.tserkovnyi@spryker.com>
Date: Mon, 8 Jan 2024 12:03:32 +0200
Subject: [PATCH 6/6] Update oryx-packages.md
---
.../oryx/getting-started/oryx-packages.md | 46 +++++++++++++++----
1 file changed, 36 insertions(+), 10 deletions(-)
diff --git a/docs/scos/dev/front-end-development/202311.0/oryx/getting-started/oryx-packages.md b/docs/scos/dev/front-end-development/202311.0/oryx/getting-started/oryx-packages.md
index b521965bb93..e6350b5b1f3 100644
--- a/docs/scos/dev/front-end-development/202311.0/oryx/getting-started/oryx-packages.md
+++ b/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.