shopware · Su (sushmangupta) · Apr 2, 2026 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026
diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -93,7 +93,7 @@ redirects:
     products/cli/project-commands/project-config-sync.html: guides/development/tooling/fixture-bundle.html
     products/sales-agent/deployment.html: products/sales-agent/best-practices/app-deployment/hosted-with-ubuntu-server.html
     guides/installation/requirements.html: guides/installation/system-requirements.html
-    guides/installation/setups/docker.html: guides/installation/docker-setup.html
+    guides/installation/setups/docker.html: guides/installation/legacy-setups/docker-setup.html
     guides/installation/template.html: guides/installation/project-overview.html
     guides/installation/setups/docker-options.html: guides/installation/advanced-options.html
     guides/installation/setups/devenv.html: guides/installation/legacy-setups/devenv-setup.html
@@ -181,3 +181,5 @@ redirects:
     resources/references/core-reference/flow-reference.html: guides/development/troubleshooting/flow-reference.html
     resources/references/core-reference/rules-reference.html: guides/development/troubleshooting/rules-reference.html
     guides/hosting/installation-updates/extension-managment.html: guides/hosting/installation-updates/extension-management.html
+    guides/installation/start-developing.html: guides/development/start-developing.html
+
diff --git a/concepts/extensions/apps-concept.md b/concepts/extensions/apps-concept.md
@@ -22,7 +22,7 @@ Shopware communicates with your app only exclusively via HTTP-Requests. Therefor
 
 ![Communication between Shopware and your app](../../assets/extensions-apps-shopwareCommunication.svg)
 
-To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. You can read more on the registration workflow in the [App base guide](../../guides/plugins/apps/app-base-guide).
+To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. See [App registration & backend setup](../../guides/plugins/apps/app-registration-setup).
 
 ::: info
 Notice that this is optional if Shopware and your app don't need to communicate, e.g., because your app provides a [Theme](apps-concept).

diff --git a/guides/development/extensions/architecture/index.md b/guides/development/extensions/architecture/index.md
@@ -1,7 +1,7 @@
 ---
 nav:
   title: Extension Architecture
-  position: 1
+  position: 10
 ---
 
 # Extension Architecture

diff --git a/guides/development/extensions/frontend.md b/guides/development/extensions/frontend.md
@@ -0,0 +1,38 @@
+---
+nav:
+  title: Build and Watch Frontend
+  position: 40
+---
+
+# Build and Watch Frontend (Storefront & Administration)
+
+Use these commands when developing or customizing the UI (Storefront or Administration), or developing extensions that affect the UI:
+
+```bash
+# Build the administration (admin panel)
+make build-administration
+
+# Build the storefront (shop frontend)
+make build-storefront
+
+# Start a watcher to rebuild the Administration automatically when files change
+make watch-admin
+
+# Start a watcher for Storefront
+make watch-storefront
+```
+
+## Alternative: Run build and watch scripts without Make
+
+You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately.
+
+The created project contains bash scripts in the `bin/` folder to build and watch the Administration and Storefront. Run the following commands:
+
+```bash
+./bin/build-administration.sh
+./bin/build-storefront.sh
+./bin/watch-administration.sh
+./bin/watch-storefront.sh
+```
+
+Use these scripts to build the Administration and Storefront. The `watch` commands monitor changes to the Administration and Storefront and automatically rebuild them.
diff --git a/guides/development/extensions/index.md b/guides/development/extensions/index.md
@@ -1,20 +1,39 @@
 ---
 nav:
   title: Extensions
-  position: 10
+  position: 1
 
 ---
 
 # Extensions
 
 As a Shopware developer, your primary focus is on developing extensions that enhance or modify Shopware's functionality.
 
-Shopware offers two extension types:
+## Server-side extension formats: plugins and bundles
 
-- **Plugins**: full system access (self-hosted only)
-- **Apps**: API-based, cloud-compatible
+Besides apps (API-based, cloud-compatible), self-hosted projects use several code extension shapes:
 
-Plugins and apps are installed and activated for the whole Shopware instance.
+| Type | Typical use | Merchant can disable in Admin? |
+|------|-------------|----------------------------------|
+| **Plugin** (`custom/plugins`) | Store extensions, distributable features | Yes (Plugin Manager) |
+| **Static plugin** (`custom/static-plugins` + Composer) | Your team’s code in Git; needs Composer dependencies | Yes (lifecycle), not listed like Store plugins—require via Composer |
+| **Shopware bundle** (`src/` or `vendor`) | Project-specific core customizations | **No** — not in Plugin Manager; always loaded |
+| **Symfony bundle** | Same as Shopware bundle, minus Shopware-specific features (themes, migrations, …) | **No** |
+
+When to choose what:
+
+* **Static plugin**: default for private project code you version in Git, especially when the plugin must declare PHP dependencies via Composer.
+* **Store-style plugin**: when you install from the Shopware Store or share a zip; lives under `custom/plugins` and is managed in the Administration.
+* **Shopware / Symfony bundle**: when code must stay active (merchants cannot deactivate it) and you want full control without plugin lifecycle UI. See the [bundle guide](../../plugins/plugins/bundle.md) and the [feature comparison](../../plugins/plugins/index.md#types-of-plugins).
+
+Plugins and apps are installed and activated for the whole Shopware instance (apps from the cloud perspective; plugins on self-hosted).
+
+## Apps and themes
+
+Shopware also offers:
+
+* **Apps**: API-based, cloud-compatible
+* **Plugins** (above): full system access (self-hosted only)
 
 :::info
 Before choosing an extension type, review the recommended [Code structure](code-structure.md). Following the standard structure reduces upgrade friction and prevents long-term maintenance issues.

diff --git a/guides/development/index.md b/guides/development/index.md
@@ -1,18 +1,15 @@
 ---
 nav:
   title: Development
-  position: 30
+  position: 1
 ---
 
 # Development
 
-This guide covers post-installation information for building, extending, and debugging Shopware during development. The development path depends on what is being built:
+After [installation](/guides/installation/index.md), use this section to extend Shopware or integrate with its APIs.
 
-* Custom project
-* Extension: apps, plugins, or plugin-based themes
-* Storefront customization
-* Administration extension
-* Headless integration
+* [Build an Extension](/guides/development/extensions/): Plugins, apps, themes, and Admin or Storefront extensions.
+* [Work with APIs](./integrations-api/index.md): making API requests, ERP, external systems, headless storefronts.
 
 All development scenarios share common foundations:
 
@@ -23,11 +20,13 @@ All development scenarios share common foundations:
 * Configuration
 * Debugging
 
-To build a custom Shopware project without creating an extension for distribution, start here.
+Before beginning implementation, review the recommended [Code structure](extensions/code-structure.md) guide. A consistent architecture prevents long-term maintenance issues and reduces upgrade friction.
+
+Before starting new development, review the [Upgrades and Migrations](../upgrades-migrations/index.md) section to avoid patterns that are deprecated or scheduled for removal.
 
 ## Extension development
 
-To build an [Extensions](extensions/index.md), first choose the correct type:
+To build an [Extension](extensions/index.md), first choose the correct type:
 
 * Plugin
 * App
@@ -49,10 +48,6 @@ Most development follows this sequence:
 * Add configuration or database changes (if required)
 * Test and debug
 
-Before beginning implementation, review the recommended [Code structure](extensions/code-structure.md) guide. A consistent architecture prevents long-term maintenance issues and reduces upgrade friction.
-
-Before starting new development, review the [Upgrades and Migrations](../upgrades-migrations/index.md) section to avoid patterns that are deprecated or scheduled for removal.
-
 :::info Upgrade impact in real projects
 Upgrade complexity depends on the installation:
 
@@ -65,28 +60,17 @@ A consistent architecture, centralized CI, and controlled extension strategy hel
 
 Set up automated testing and [Continuous Integration (CI)](testing/ci.md) early. Static analysis, tests, and reproducible builds help catch breaking changes before they reach production.
 
-## Working in the system
-
-### Administration
-
-To begin any development, first access the Administration by opening [http://localhost/admin](http://localhost/admin).
-
-Use the Administration to:
-
-* Install and activate extensions
-* Configure the system
-* Manage entities such as products and customers
-* Verify extension behavior
-
-The Administration is part of the runtime environment and will be used throughout development.
-
-### Development tooling
+## Development tooling
 
 * `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md).
 * The standalone [Shopware CLI](../../products/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/cli/project-commands/helper-commands.md).
 * IDE support: Shopware provides a [PHPStorm plugin](tooling/shopware-toolbox.md) and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=shopware.shopware-lsp).
 * [Deployment Helper](../hosting/installation-updates/deployments/deployment-helper.md):  Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
 
-### Troubleshooting
+## Troubleshooting
 
 The [troubleshooting](troubleshooting/index.md) guides provide reference information about the data abstraction layer (DAL), flow, and rules.
+
+## Next steps
+
+Move on to the [Start developing guide](start-developing.md).
diff --git a/guides/development/integrations-api/auth-api-requests.md b/guides/development/integrations-api/auth-api-requests.md
@@ -0,0 +1,122 @@
+---
+nav:
+  title: Authentication and API Requests
+  position: 20
+---
+
+
+# Authentication and API Requests
+
+This guide builds on the [APIs](./index.md) guide and covers additional authentication details, practical request patterns, and troubleshooting for local development.
+
+## Local password-grant shortcut
+
+The [APIs](./index.md) guide uses integrations with `client_credentials`, which should remain the default approach.
+
+For local development only, you can also obtain an Admin API token with the default Administration credentials:
+
+```bash
+curl -X POST "http://localhost:8000/api/oauth/token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "grant_type": "password",
+    "client_id": "administration",
+    "scopes": "write",
+    "username": "admin",
+    "password": "shopware"
+  }'
+```
+
+Example response:
+
+```json
+{
+  "token_type": "Bearer",
+  "expires_in": 600,
+  "access_token": "...",
+  "refresh_token": "..."
+}
+```
+
+Use this only as a local shortcut. For integrations and reproducible setups, prefer `client_credentials` as described in the [APIs](./index.md) guide.
+
+## Prefer search endpoints for real requests
+
+For most real Admin API work, prefer search endpoints over simple entity listing routes.
+
+Instead of:
+
+```bash
+curl "http://localhost:8000/api/product" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+use:
+
+```bash
+curl -X POST "http://localhost:8000/api/search/product" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Search endpoints support:
+
+- filtering
+- sorting
+- pagination
+- associations
+
+## Download the OpenAPI schema
+
+Shopware exposes OpenAPI schemas for both Admin API and Store API. These schemas are generated via PHP annotations using [swagger-php](https://github.com/zircote/swagger-php). When building custom endpoints, you can leverage these annotations to generate standardized documentation for them.
+
+To work with the raw schema instead of the local browser reference, download it directly:
+
+```bash
+curl -X GET "http://localhost:8000/api/_info/openapi3.json" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -o openapi.json
+```
+
+::: warning
+Due to security restrictions, your `APP_ENV` environment variable must be set to `dev` to access the specifications described below.
+:::
+
+Raw schema endpoints: `/(api|store-api)/_info/openapi3.json`.
+
+Entity schema endpoints: `/(api|store-api)/_info/open-api-schema.json`.
+
+## Troubleshooting local request failures
+
+If you encounter errors like:
+
+- `Table 'shopware.system_config' doesn't exist`
+- `Table 'shopware.plugin' doesn't exist`
+- `HTTP 500 on /api/_info/openapi3.json`
+
+your database may not be initialized.
+
+Run:
+
+```bash
+docker compose exec web bin/console system:install --create-database --basic-setup
+```
+
+If issues persist:
+
+```bash
+docker compose down -v
+rm install.lock
+docker compose up -d
+docker compose exec web bin/console system:install --create-database --basic-setup
+```
+
+## Next steps
+
+Learn how to structure queries using:
+
+- [Search Criteria](../integrations-api/search-criteria.md): encapsulates the entire search definition in one generic object
+- [Request Headers](../integrations-api/request-headers.md): additional instructions
+- [Partial Data Loading](../integrations-api/partial-data-loading.md)
diff --git a/guides/development/integrations-api/generated-reference.md b/guides/development/integrations-api/generated-reference.md
@@ -1,7 +1,7 @@
 ---
 nav:
   title: Generated Reference
-  position: 30
+  position: 60
 
 ---