--- title: 'Administration: The Shopware Object | Shopware Community Hub' description: >- Learn how the global Shopware object extends the browser runtime, connects plugin code with the administration, and helps you inspect administration… canonical_url: 'https://hub.shopware.com/learn/unit/administration-the-shopware-object' --- # Administration: The Shopware Object - Understand how `window.Shopware` extends the browser runtime for administration development. - Learn why the `Shopware` object is the central entry point for modules, components, services, snippets, and administration context. - Identify important sub-objects such as `Module`, `Component`, `Service`, `Locale`, `Context`, and `Utils`. - Use the `Shopware` object in the browser console to inspect modules, components, snippets, services, shortcuts, and other administration structures. # Administration: The Shopware Object You already registered a custom module via `Shopware.Module.register()`. But what is the `Shopware object`? Let's find out. ## What is the Shopware Object? The Shopware object is the **central entry point** of the Shopware administration. It connects your plugin with the Shopware administration and acts as the bridge between your custom code and Shopware's internal system. It provides access to everything that happens inside the administration from modules and components to filters, services, and enabling you to extend and interact with the system safely and consistently. ## Where is the Shopware Object Available? You already know the basic browser model from the storefront JavaScript section: The `window` object is the global root object of the Browser Object Model (BOM). The administration uses the same browser root object. The difference is what Shopware attaches to it. ## How Shopware Extends the BOM In the administration, Shopware adds one central global object: `Shopware`. That object is attached to the browser root object: ```js window.Shopware; ``` The `Shopware` object is structured as the central JavaScript entry point for the administration. It connects the browser runtime with Shopware's administration system and gives plugin code access to modules, components, services, snippets, the application context, and other administration features. So, every time you see a function like `Shopware.Module.register()`, the full path behind it is: ```js window.Shopware.Module.register(); ``` Let's look at what this means in the extended BOM: ![BOM with Shopware](assets/images/browser-object-model-extended-administration.jpg) The important idea is simple: In administration development, `Shopware` is your central access point. The next sections show which sub-objects you will use most often. ## What Does the Shopware Object Provide? The `Shopware` object exposes many of the building blocks you use when extending the administration. The following sections give you a practical overview of the most important sub-objects. You do not need to memorize all of them. The goal is to know what exists and where to look during development. ### Core Objects These are the building blocks that define and extend Shopware's Vue-based administration structure. They are mainly used to register or extend UI-related elements. #### Module As you already know, it registers and manages modules in the administration. Each module defines its own routes, navigation entries, snippets, and metadata. Modules are the highest organizational level inside the administration; Every page or component is part of a module. #### Component As you already know, it registers, extends, or overrides Vue (reusable) components globally. It makes components reusable across multiple modules and allows you to extend existing Shopware UI components safely. **Example: Register a component** ```js import template from './sw-my-component.html.twig'; Shopware.Component.register('sw-my-component', { template: template, data(){ return { message: 'Hello from my custom component!' } } }); ``` **Example: Extend an existing component** ```js Shopware.Component.extend( 'sw-price-preview', // (A) = The new extension component 'sw-price-field', // (B) = The base component () => import('./base/sw-price-preview/index') // The configuration of (A) ); ``` In this example, the component `sw-price-preview` is created as a new component (A) that extends the existing `sw-price-field` component (B). The configuration file defines how the new component (A) builds on or overrides the behavior of its base **without** directly modifying the base component (B). #### Filter Registers filters globally. Filters allow you to transform data directly in Vue templates. You can also access and use them programmatically via `Shopware.Filter.getByName()`. **Example: Register a filter** ```js Shopware.Filter.register('capitalize', (value: string) => { if (!value) { return ''; } value = value.toString(); return value.charAt(0).toUpperCase() + value.slice(1); }); ``` **Example: Use a filter** In this example, the filter `capitalize` is used on the string `shopware`. ```js import template from './sw-my-component.html.twig'; Shopware.Component.register('sw-my-component', { template, computed: { capitalizedString() { return Shopware.Filter.getByName('capitalize')('shopware'); } } }); ``` Or directly in the Twig template: ```twig {% block my_custom_block %} {{ 'my string'|capitalize }} {% endblock %} ``` #### Mixin Registers reusable mixins (functions) that can be injected into multiple components. Mixins help you share common logic – methods, computed properties, lifecycle hooks – across components without duplication. Similar to components: Components are reusable building blocks for UI, while mixins are **reusable logic blocks** used across multiple components. **Example: Register a mixin** ```js Shopware.Mixin.register('sw_greet_user', { methods: { greetUser(name: string) { return `Hello ${name}!`; } } }); ``` **Example: Use the mixin in a component** ```js import template from './sw-my-component.html.twig'; Shopware.Component.register('sw-my-component', { template, mixins: [ Shopware.Mixin.getByName('sw_greet_user') ], created() { console.log(this.greetUser('Cody')); } }); ``` In this example, we use the mixin `sw_greet_user` in the component `sw-my-component`. The mixin provides a method `greetUser()` that can be used in the component. In the `created()` lifecycle hook, we call the method and log the result. #### Directive Registers custom Vue directives that can be used directly in templates. Directives are small, reusable **behaviors** that you attach to **DOM elements** – for example, to handle user interactions such as copying text, showing tooltips, focusing an element or reacting to clicks outside the element. **Example: Register a directive** ```js Shopware.Directive.register('copy-on-click', { bind(el) { el.addEventListener('click', () => { const text = el.innerText; navigator.clipboard.writeText(text); }); }, unbind(el) { el.removeEventListener('click'); } }); ``` **Example: Use the directive in a template** ```js Copy me! ``` When the user clicks on the span element, its text `Copy me!` will be copied to the clipboard. This example shows how directives help you to encapsulate small, DOM-based behaviors and reuse them across components without repeating the same logic. You can differentiate between **components**, **mixins**, and **directives** as follows: - **Components** are reusable building blocks for UI. - **Mixins** are reusable **logic blocks** used across multiple components. - **Directives** are reusable DOM behaviors. #### Plugin The `Plugin` object provides an interface **to add promise-based hooks** that run when the administration launches. It is not related to Shopware's PHP plugin system – instead, it allows you to attach custom JavaScript logic that executes during the bootstrapping phase of the administration. The bootstrapping phase is the startup phase in the browser when you open or refresh the administration. During this phase, Shopware: - Loads the administration JavaScript - Initializes core services - Registers modules, components, routes, and snippets. After this process is finished, the administration UI is ready to use. This is especially useful for initializing global services, registering listeners, or performing setup tasks before modules and components are loaded. **Example: Custom error logger** ```js Shopware.Plugin.register('my-error-logger', () => { return new Promise((resolve) =>{ window.addEventListener('error', (event) => { console.warn('[MyLogger] Error captured: ', event.message); // Send error details to your server }); console.log('[MyLogger] Global error listener initialized.'); resolve(); }); }); ``` In this example, a global error listener is registered when the administration starts. It captures all JavaScript errors, logs them in the console, and could optionally send them to a monitoring service. The `resolve()` call ensures that the administration continues to boot once initialization is complete. ### Services and Helpers These objects handle data access, default values, application context, and shared logic. They are the backbone of how the administration communicates and processes data. #### Service Services are Shopware-specific utilities that provide reusable logic for common tasks such as data handling and UI-related operations. Unlike mixins, which are limited to Vue components, services are **independent** and can be used anywhere in your plugin. They often act as an **interface to core functionality**, such as the `snippetService` or the `repositoryFactory`. So they are the central access layer for logic and data that should be shared consistently across modules and components. #### Utils The `Utils` collection contains a lot of reusable helper functions – from generating IDs to working with strings, dates, or objects – that simplify the development process. These functions are **completely independent** and can be used anywhere in your plugin – in components, mixins, services or even plain JavaScript files. **Example: Generate a unique ID** ```js const id = Shopware.Utils.createId(); ``` **Example: Merge two configuration objects** ```js const defaults = { title: 'My Module', settings: { visible: true, limit: 10 } }; const custom = { settings: { limit: 5 } }; const merged = Shopware.Utils.object.merge(defaults, custom); console.log(merged); // { title: 'My Module', settings { visible: true, limit: 5 } } ``` You can find a list of all available helper functions in the [official repository](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/service/util.service.ts#L153). You may ask: What is the difference between `Mixins`, `Services` and `Utils`? - **Mixins** share logic inside Vue components (methods, computed properties, lifecycle hooks). - **Services** are global and context-aware. They can be injected and reused anywhere in the administration. - **Utils** are pure, **generic** helper functions. They don't depend on Vue or Shopware context and can be used anywhere, even outside a module. #### Defaults The `Defaults` collection contains **global default values** used throughout the administration such as the `systemLanguageId`, `defaultSalutationId`, `defaultLanguageIds` and more. These constants ensure consistent behavior and can be used whenever you need to reference system-wide defaults or provide a reliable fallback value. **Example:** ```js Shopware.Store.get('context').api.languageId = localStorage.getItem('sw-admin-current-language') || Shopware.Defaults.systemLanguageId; ``` In this example, it checks if a language is set in the `localStorage` and if not, it uses the default language of the administration system. #### State The `State` collection is a wrapper around the VueX. It provides a simple and consistent way to store, read, and update shared data across the entire administration. This ensures that all modules and components work with a unified and predictable state layer. The state system allows multiple areas of the administration to stay synchronized — for example, when a product is updated on a view, the change is immediately reflected in another. You can explore which state Shopware provides in the [state factory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/state.factory.ts#L45). #### Context The `Context` defines **app** and **api** contexts, helping Shopware differentiate between client-side and backend operations. It provides environment-specific data such as language, currency or permissions. ```js const apiContext = Shopware.Context.api; console.log(apiContext.languageId); // Current language id of the administration ``` You can use `Shopware.Context.api` for API-related operations and `Shopware.Context.app` for client-side operations. A list of properties can be found [here](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/app/composables/use-context.ts#L16). #### ApiService The `ApiService` is the foundation for all API-related operations in the administration. It provides a consistent way to fetch, create, update, or delete data through the API. That means, you don't need to write your own `fetch` or `axios` calls. Shopware wraps these operations into services, so you can use them in your plugin and follow the same structured pattern used by the core system itself. There are two types of API services: - **Core services**, which Shopware provides out of the box (e.g., `repositoryFactory`, `loginService`, `mediaService`). - **Custom services**, which you can create to interact with your own API endpoints. All services use the same base layer, the `ApiService`. It automatically handles things like authentication, error handling, and language context. In short: The `ApiService` is the **data bridge** between your plugin and the Shopware backend. It keeps your communication layer clean, safe, and standardized. #### Helper The `Helper` collection provides grouped utility objects that make working with the administration easier. Each helper focuses on a specific task, for example, detecting the current device type (`DeviceHelper`), handling input events (`SanitizerHelper`), or refreshing API tokens (`RefreshTokenHelper`). Helpers are available globally through the `Shopware.Helper` object. They are not tied to Vue and help you handle common technical or browser-related tasks in a clean and reusable way. ### Developer Tools and Localization These objects support developers with debugging, keyboard shortcuts, and localization. They are useful during development and UI customization. #### Locale The `Locale` object manages all available languages (locales) and their translation trees inside the administration. You can register new locales (e.g., `en-GB` or `ch-DE`), extend existing locales, and access them globally across the administration blocks. You might wonder – if we already use the `$t()` function for translations in template, why do we also have the `Locale` object? The reason is: the `Locale` object is the **global registry** that stores all translation data, while `$t()` is simply a **Vue-level helper** that looks up translations from this registry at runtime. In other words: - `Shopware.Locale` = manages and provides all translations system-wide. - `$t()` = reads from it within Vue templates. **Example: Show all translations of `swag-example` in German** The `swag-example` name is only used here because older Shopware examples and generated skeletons often use it. For your own modules, choose your own project or company prefix. ```js Shopware.Locale.getByName('de-DE')['swag-example'] ``` #### Shortcut The `Shortcut` object allows you to register custom keyboard shortcuts inside the administration. This enables the user of the administration to improve usability and speed up common tasks, for example, save (Ctrl + S) or reload (Ctrl + R). **Example: Register a shortcut** ```js Shopware.Shortcut.register('CTRL+SHIFT+H', 'my-custom-route'); ``` **Example: Inspect all registered shortcuts** ```js Shopware.Shortcut.getShortcutRegistry(); ``` Before creating a shortcut, check which keys are already in use and create a unique key combination. An override of existing combinations is not possible. --- The `Shopware` object contains more sub-objects than this learning unit can cover in detail. For a broader reference, see the [official overview](https://developer.shopware.com/docs/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.html#a-more-general-overview). ## Debugging the Shopware Object The `Shopware` object is globally available in the browser's console. This makes it an excellent entry point for **debugging** and **exploring** how the administration works internally. The following tables give you an overview of **useful debugging commands**, grouped by topic. ### Modules and Components | What you want to inspect | Command | Description | |--------------------------------------------------|----------------------------------------------------------------------|-------------------------------------------| | All registered modules | `Shopware.Module.getModuleRegistry()` | Returns a list of all registered modules. | | A specific module (e.g., `swag-example`) | `Shopware.Module.getModuleRegistry().get('swag-example')` | Looks up a single module by its name. | | All registered components | `Shopware.Component.getComponentRegistry()` | Lists all registered components. | | A specific component (e.g., `swag-example-list`) | `Shopware.Component.getComponentRegistry().get('swag-example-list')` | Looks up a single component by its name. | ### Localization and Snippets | What you want to inspect | Command | Description | |---------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------| | All registered locales | `Shopware.Locale.getLocaleRegistry()` | Lists all available locales and their metadata. | | All snippets for a locale (e.g., `de-DE`) | `Shopware.Locale.getByName('de-DE')` | Lists all translation snippets for the given locale. | | All snippets for your module in a specific locale | `Shopware.Locale.getByName('de-DE')['swag-example']` | Shows only the translations for your module and locale. | | System default values (e.g., `systemLanguageId`) | `Shopware.Defaults` | Shows default IDs and other system-wide constants. | ### Filters and Mixins | What you want to inspect | Command | Description | |-------------------------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------| | All registered filters | `Shopware.Filter.getRegistry()` | Returns a list of all registered filter. | | A specific filter(e.g., `currency`) | `Shopware.Filter.getRegistry().get('currency')` or `Shopware.Filter.getByName('currency')` | Looks up a single filter instance. | | A specific mixin by name | `Shopware.Mixin.getByName('mixin-name')` | Returns a single mixin configuration by its name. | ### Context, Shortcuts, Directives | What you want to inspect | Command | Description | |-----------------------------------|---------------------------------------------|-------------------------------------------| | Global context (app, api, etc.) | `Shopware.Context` | Lists core context objects and values. | | All registered keyboard shortcuts | `Shopware.Shortcut.getShortcutRegistry()` | Shows all shortcuts currently registered. | | All registered directives | `Shopware.Directive.getDirectiveRegistry()` | Lists all registered directives. | ### Services and Plugins | What you want to inspect | Command | Description | |---------------------------------|------------------------------------------------|--------------------------------------------------------------------------------------------------| | Global context (app, api, etc.) | `Shopware.Application.getContainer('service')` | Lists all registered services in the dependency injection container, including your custom ones. | | Plugin boot promises | `Shopware.Plugin.getBootPromises()` | Lists promises used while booting plugins. | --- These examples give you a great starting point for debugging and understanding how the `Shopware` object is structured and how your custom code integrates into it. ## Why This Architecture? You might wonder why the Shopware administration uses Vue.js, while the storefront uses Twig. The reason is the different purpose and complexity of both systems and a bit of historical context. The storefront is not as complex as the administration. It was built using a static, server-side rendered HTML/Twig structure focused on speed, SEO, and simplicity. This makes it ideal for presenting products to customers effectively and keeping pages lightweight. On the other hand, the administration has completely different requirements. It needed to be a highly dynamic single-page application, where merchants can manage thousands of products, open multiple sections, and switch between areas instantly **without reloading the page**. For this kind of interactivity and modularity, Vue.js was the perfect choice. In short: The **administration** is a **complex**, **dynamic** application that **constantly interacts** with data and state. Therefore, it was built with Vue.js. Keep in mind that you are not developing with Vue.js alone, but rather extending Shopware's administration system, which uses Vue.js under the hood. ## Summary In this learning unit, you learned what the `Shopware` object is and how it connects your plugin code to the administration. By now, you should be able to: - Explain how `window.Shopware` extends the browser runtime for administration development. - Understand why the `Shopware` object is the central entry point for administration extensions. - Identify important sub-objects such as `Module`, `Component`, `Service`, `Locale`, `Context`, and `Utils`. - Use the browser console to inspect registered modules, components, snippets, services, and shortcuts. - Understand how the `Shopware` object helps you explore and debug administration behavior during development. With this understanding, you are ready to use the `Shopware` object more confidently when building and debugging administration extensions. **Congratulations!** By completing this learning unit, you have also completed this course! In the next course, you will dive deeper into the Shopware administration and apply your knowledge in **hands-on**, **practical** examples.