Context

The Context API provides read access to the current state of the Shopware Administration. Extensions can use these methods to retrieve information about the active language, locale, currency, environment, Shopware version, and more.

This is useful for adapting extension behavior based on the current Administration context — for example, loading translations for the active language, matching the active color theme, or checking the Shopware version before using a newer API.

import { context } from "@shopware-ag/meteor-admin-sdk";

getLanguage()

Returns the current Administration language ID and the system default language ID. Use this to load the correct translations or filter data by language.

Usage

const language = await context.getLanguage();

Parameters

No parameters needed.

Return value

Promise<{
  languageId: string;
  systemLanguageId: string;
}>

Example value

{
  languageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b',
  systemLanguageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b'
}

subscribeLanguage()

Subscribes to language changes in the Administration. The callback fires whenever the user switches languages, allowing extensions to react immediately (e.g. reloading translated content).

Usage

context.subscribeLanguage(({ languageId, systemLanguageId }) => {
  // do something with the callback data
});

Parameters

Name	Description
callbackMethod	Called every-time the language changes

Callback value

{
  languageId: string,
  systemLanguageId: string
}

Example callback value

{
  languageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b',
  systemLanguageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b'
}

getEnvironment()

Returns the current Administration environment mode. Use this to enable debug features or disable analytics in non-production environments.

Usage

const environment = await context.getEnvironment();

Parameters

No parameters needed.

Return value

Promise<"development" | "production" | "testing">

Example value

"development";

getLocale()

Returns the browser locale used by the Administration UI, including a fallback locale. Use this to format dates, numbers, or currencies according to the user's regional settings.

Usage

const locale = await context.getLocale();

Parameters

No parameters needed.

Return value

Promise<{
  locale: string;
  fallbackLocale: string;
}>

Example value

{
  locale: 'de-DE',
  fallbackLocale: 'en-GB'
}

subscribeLocale()

Subscribes to locale changes in the Administration. The callback fires whenever the locale changes, allowing extensions to re-render locale-dependent content like formatted dates or currencies.

Usage

context.subscribeLocale(({ locale, fallbackLocale }) => {
  // do something with the callback data
});

Parameters

Name	Description
callbackMethod	Called every-time the locale changes

Callback value

{
  locale: string,
  fallbackLocale: string
}

Example callback value

{
  locale: 'de-DE',
  fallbackLocale: 'en-GB'
}

Automatic theme synchronization

On startup, the SDK mirrors the resolved Administration theme onto the data-theme attribute and the color-scheme style of your document root (<html data-theme="light|dark">) and keeps both in sync. Because Meteor tokens are theme-aware through data-theme, updating the SDK dependency is all an app needs to follow the Administration theme. The matching color-scheme keeps the iframe transparent: on a mismatch the browser paints an opaque backdrop behind it.

The initial theme is read from the color-scheme URL param that theme-aware Administrations append to the iframe src, so the correct scheme is applied before the first paint. Administrations without theme support do not send the param; in that case the document is pinned to the light scheme, which matches those Administrations and prevents the OS dark mode preference from leaking into the app. Later theme changes arrive through the regular sync.

If your document already declares data-theme itself, the SDK does not interfere. In that case, declare a matching color-scheme in your own styles: without one the browser falls back to the light scheme and paints an opaque backdrop behind the iframe in a dark Administration. On Administrations without theme support, the attribute is never set.

Embedded context

When your app runs inside an iframe, the SDK marks the document root with a data-embedded attribute (<html data-embedded>) on startup, so stylesheets can adapt to the embedded context. It also unsets the body background (html[data-embedded] body { background: unset; }) as a sensible default for iframes inside of the administration.

If your document already declares data-embedded itself, the SDK keeps your value.

getTheme()

Returns the current resolved color theme of the Administration. A system preference is always resolved, so the result is either "light" or "dark".

Usage

const theme = await context.getTheme();

Parameters

No parameters needed.

Return value

Promise<"light" | "dark">

Example value

"dark";

subscribeTheme()

Subscribes to theme changes in the Administration. The callback fires whenever the resolved theme changes. Returns a function that stops the subscription.

Usage

context.subscribeTheme((theme) => {
  // do something with the callback data
});

Parameters

Name	Description
callbackMethod	Called every time the resolved theme changes

Callback value

"light" | "dark"

Example callback value

"dark";

syncTheme()

Mirrors the Administration theme onto an element's data-theme attribute and keeps it in sync. The document root is already handled by the automatic theme synchronization; use this when you manage data-theme yourself or need the attribute on additional elements.

Usage

const stopSync = await context.syncTheme({ target: document.getElementById("app") });

Parameters

Name	Description
options.target	Element whose data-theme attribute is updated. Defaults to document.documentElement

Return value

Promise<() => void>

The returned function stops the synchronization.

getCurrency()

Returns the system currency configured for the Shopware instance. Use this when displaying prices or working with monetary values.

Usage

const currency = await context.getCurrency();

Parameters

No parameters needed.

Return value

Promise<{
  systemCurrencyId: string;
  systemCurrencyISOCode: string;
}>

Example value

{
  systemCurrencyId: 'b7d2554b0ce847cd82f3ac9bd1c0dfca',
  systemCurrencyISOCode: 'EUR'
}

getShopwareVersion()

Returns the Shopware version as a string. Use this to conditionally enable features or check compatibility before using newer APIs.

Usage

const shopwareVersion = await context.getShopwareVersion();

Parameters

No parameters needed.

Return value

string

Example value

"6.4.0.0";

compareIsShopwareVersion()

Compares the current Shopware version against a target version. The current Shopware version is always the left-hand side of the comparison — so context.compareIsShopwareVersion('>=', '7.0.0') reads as "is the current Shopware version equal to or greater than 7.0.0?"

Usage

const isRightVersion = await context.compareIsShopwareVersion(">=", "7.0.0");

Parameters

Name	Description
comparator	The operator to compare. Possible values: '=' '!=' '>' '<' '<=' '>='
version	The string with the version to compare

The function supports both Shopware's four-digit version number and semver versions. The following calls are equivalent:

await context.compareIsShopwareVersion(">=", "6.6.4.0");

await context.compareIsShopwareVersion(">=", "6.4.0");

Return value

boolean

Example value

true;

getAppInformation()

Returns metadata about the current app or plugin, including its name, version, type, and granted privileges. Use this to adapt behavior based on the extension type or check which permissions were granted.

The privileges property is available since Shopware v6.7.1.0.

Usage

const { name, version, type, privileges } = await context.getAppInformation();

Parameters

No parameters needed.

Return value

Promise<{
  name: string;
  version: string;
  type: "app" | "plugin";
  privileges: privileges;
}>

Example value

{
  name: 'my-extension',
  version: '1.2.3',
  type: 'app',
  privileges: {
    read: [ 'product', 'customer' ],
    update: [ 'product' ],
    additional: [ 'system.cache_clear' ]
  }
}

getUserInformation()

Returns details about the currently logged-in Administration user, including their roles, email, and admin status. Use this to personalize the extension UI or check user permissions.

Available since Shopware v6.4.9.0

Usage

const userInformation = await context.getUserInformation();

Parameters

No parameters needed.

Return value

Promise<{
  aclRoles: Array<{
    name: string;
    type: string;
    id: string;
    privileges: Array<string>;
  }>;
  active: boolean;
  admin: boolean;
  avatarId: string;
  email: string;
  firstName: string;
  id: string;
  lastName: string;
  localeId: string;
  title: string;
  type: string;
  username: string;
}>

Example value

{
    "aclRoles": [],
    "active": true,
    "admin": true,
    "avatarId": "",
    "email": "info@shopware.com",
    "firstName": "",
    "id": "e2a77f4c718d407591b4826222aa3546",
    "lastName": "admin",
    "localeId": "35bbb8c4305c47ec88b13ab30c0c5c5a",
    "title": "",
    "type": "user",
    "username": "admin"
}

getUserTimezone()

Returns the timezone setting of the currently logged-in user. Use this to display dates and times in the user's local timezone.

Available since Shopware v6.6.2.0

Usage

const userTimezone = await context.getUserTimezone();

Parameters

No parameters needed.

Return value

Promise<string>

This function returns a Promise that resolves to a string representing the user's timezone.

getModuleInformation()

Returns the list of all registered extension modules (created by adding menu items, settings items, etc.). Use the module ID to navigate between extensions.

Usage

import { window as swWindow } from "@shopware-ag/meteor-admin-sdk";

const { modules } = await context.getModuleInformation();

swWindow.routerPush({
  name: "sw.extension.sdk.index",
  params: {
    id: modules[0].id,
  },
});

Parameters

No parameters needed.

Return value

Promise<{
  modules: Array<{
    displaySearchBar: boolean;
    heading: string;
    id: string;
    locationId: string;
  }>;
}>

Example value

{
  modules: [
    {
      displaySearchBar: true,
      heading: "My module",
      id: "sd5aasfsdfas",
      locationId: "my-location-id",
    },
  ];
}

getShopId()

Returns the unique shop ID used by Shopware's app system. Use this to identify the shop instance when communicating with external services.

Available since Shopware v6.7.1.0

Usage

const shopId = await context.getShopId();

Parameters

No parameters needed.

Return value

Promise<string | null>

can()

Checks whether a specific privilege is granted for the current app. Use this to conditionally show features that require specific permissions.

Available since Shopware v6.7.1.0

Usage

const isAllowed: boolean = await context.can("product:read");

Parameters

Name	Description
privilege	The privilege string to check, e.g. 'product:read'

Return value

boolean