diff --git a/products/cli/project-commands/build.md b/products/cli/project-commands/build.md
index e809478706..2138bc9adb 100644
--- a/products/cli/project-commands/build.md
+++ b/products/cli/project-commands/build.md
@@ -174,6 +174,11 @@ build:
   # Allows force building an extension even when the assets exist. A use-case could be if you used composer patches for a specific extension.
   force_extension_build:
     - name: 'SomePlugin'
+  # Shopware bundles to include in the build (alternative to composer.json extra.shopware-bundles)
+  bundles:
+    - path: src/MyBundle
+    - path: src/MyFancyBundle
+      name: MyGreatFancyBundle
   # MJML compilation configuration (see the MJML section above for details)
   mjml:
     enabled: false
@@ -193,7 +198,25 @@ build:
 ## Supporting bundles
 
 Shopware CLI automatically detects plugins and Apps. Custom bundles (classes that extend bundle class from Shopware) cannot be automatically detected as Shopware CLI does not execute any PHP code.
-Therefore, you need to add the path of the custom bundle to your project `composer.json`:
+You can declare bundles in either your `.shopware-project.yml` or the project `composer.json`.
+
+### Declaring bundles in `.shopware-project.yml`
+
+The recommended approach is to declare bundles in the `build` section of your `.shopware-project.yml`:
+
+```yaml
+build:
+  bundles:
+    - path: src/MyBundle
+    - path: src/MyFancyBundle
+      name: MyGreatFancyBundle  # optional: override the bundle name (defaults to the directory name)
+```
+
+The `path` is relative to the project root. The `name` field is optional and when omitted, the bundle name defaults to the directory basename.
+
+### Declaring bundles in `composer.json`
+
+Alternatively, you can add the bundle path to the `extra` section of your `composer.json`:
 
 ```json5
 {
@@ -206,7 +229,7 @@ Therefore, you need to add the path of the custom bundle to your project `compos
 }
 ```
 
-If your bundle folder name does not match your bundle name, you can use the `name` key to map the folder to the bundle name.
+If your bundle folder name does not match your bundle name, you can use the `name` key:
 
 ```json
 {
@@ -220,6 +243,8 @@ If your bundle folder name does not match your bundle name, you can use the `nam
 }
 ```
 
+Both sources are merged automatically. If the same bundle path appears in both, it is only processed once.
+
 ### Bundle packaged in own composer package
 
 If your bundle is an own composer package, make sure your composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the extra part of the config like this: