Shopware 6’s administration panel has long been praised for its flexibility and intuitive design, but its true power lies in extensibility. While core functionality covers e-commerce essentials out of the box, modern storefront operations often demand specialized workflows, internal tools, or merchant-facing dashboards that simply don’t exist in the base installation. This is where custom admin modules shine.

Shopware 6.7 represents a significant architectural shift for the administration layer. The underlying stack now embraces modern JavaScript tooling, ESM module resolution, Vue 3 with Pinia state management, and stricter type safety by default. Understanding these changes is crucial before diving into custom module development. This guide walks you through the conceptual and practical steps of creating a custom admin module in Shopware 6.7+, focusing on architecture, registration, and best practices rather than boilerplate code.

Prerequisites & Foundation

Before writing a single line of module code, ensure your environment aligns with Shopware 6.7 requirements:

  • PHP 8.2 or higher with Composer dependencies fully resolved
  • A properly structured plugin base following PSR-4 conventions
  • Familiarity with Vue 3’s Composition API and Pinia state management
  • Access to the Shopware CLI (bin/administration/)

Shopware 6.7 streamlines module scaffolding by defaulting to TypeScript and ESM. The old JavaScript-heavy templates are deprecated in favor of stricter, type-safe structures that integrate seamlessly with modern build pipelines.

Step 1: Scaffold the Module Structure

Shopware 6.7 provides an official CLI tool that respects your plugin’s namespace and generates a convention-aligned module skeleton. Run:

bin/administration/create-module.sh YourPlugin custom-dashboard

This command creates a directory under Administration/src/modules/custom-dashboard/ with subfolders for components, API calls, routes, and permissions. The CLI automatically configures the module to be discoverable by Shopware’s plugin system in 6.7+. Note that you no longer need to manually edit src/Administration/module/index.js as was required in earlier versions; discovery is now automatic when placed within the plugin’s Administration/ root.

Step 2: Understand the New Module Anatomy

In Shopware 6.7, each module folder follows a strict convention that separates concerns while enabling fast compilation:

  • index.ts: Exports the module definition and routes
  • page/ or component/: Vue files using Composition API
  • api/: Service classes interacting with Symfony route controllers
  • route/ & permission/: Routing metadata and ACL rules

The administration system expects modules to expose a default export containing module name, icon, label, routes, and optional breadcrumbs. Shopware 6.7’s build process automatically tree-shakes unused paths and bundles them per-request or precompiles them during bin/build-administration.sh. This means your module should remain lightweight and avoid heavy third-party dependencies that bloat the admin bundle size.

Step 3: Registering & Routing in Shopware 6.7+

While automatic discovery handles most registration, explicit permission and route configuration remains necessary. In Shopware 6.7, routes are defined as a collection of Shopware\Administration\Routing\Route objects. Each route requires:

  • A unique path identifier
  • A component reference (Vue file)
  • Meta data for breadcrumbs and labels

Permissions are no longer hardcoded. Instead, Shopware 6.7 uses permissions.json at the module root to declare granular ACL rules. For example:

{
  "custom_dashboard:view": {
    "parent": "framework",
    "permissions": [],
    "collection": []
  }
}

You then map this permission in your route metadata. The administration panel will automatically gate access based on the logged-in admin user’s rights, enforcing a secure-by-default model without manual checks in templates.

Step 4: Connecting to the Backend API

Shopware 6.7 encourages decoupled API communication. Create an api/CustomDashboardApi.ts file that wraps SwHttpClient calls to your Symfony route controller. Ensure your controller extends Symfony\Bundle\FrameworkBundle\Controller\AbstractController, returns JSON, and respects CSRF if modifying data. In the admin module, use Pinia stores to cache responses and manage loading states, avoiding repeated API calls during navigation.

Best Practices for Shopware 6.7+

  • Prefer TypeScript: Even for simple modules, strict typing prevents runtime errors in the compiled admin bundle.
  • Split Components: Keep pages under 300 lines. Extract tables, forms, and modals into reusable components.
  • Lazy Load Routes: Use dynamic imports in your route definition to reduce initial admin load time.
  • Test Permissions Early: Verify ACL behavior with multiple admin roles during development, not after deployment.
  • Respect Bundle Limits: The administration panel loads all active modules on startup. Unused or bloated modules degrade UX across the entire backend.

Conclusion

Building a custom admin module in Shopware 6.7+ is less about fighting the framework and more than adapting to its modernized architecture. By leveraging the CLI scaffold, respecting the ESM/TypeScript default, configuring permissions declaratively, and keeping components modular, you can deliver tailored merchant experiences without compromising performance or security. Always reference the official Shopware documentation for your specific version, as administrative conventions continue to evolve toward tighter integration with Symfony routing, Vue 3 lifecycle hooks, and automated permission auditing. With careful planning and incremental testing, your custom module will become a seamless extension of the Shopware admin ecosystem.