Skip to main content

​
Quickstart Guide

This guide will walk you through creating a basic admin app that extends the Shopware 6 Administration. You’ll learn how to set up the SDK, register UI extensions, and display content in the admin interface.

​
What You’ll Build

In this tutorial, you’ll create a simple admin app that:
  • Adds a custom menu item to the administration
  • Displays a card on the dashboard
  • Shows a notification when loaded
1

Create Your Project Structure

First, create a basic HTML file for your admin app:
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Admin App</title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="./main.js"></script>
</body>
</html>
2

Install the Admin SDK

Install the SDK using npm:
npm install @shopware-ag/meteor-admin-sdk
Or use the CDN version by adding this script tag to your HTML:
<script src="https://unpkg.com/@shopware-ag/meteor-admin-sdk/cdn"></script>
3

Initialize Your App

Create a main.js file that checks the location context and initializes your app:
import { location } from '@shopware-ag/meteor-admin-sdk';

if (location.is(location.MAIN_HIDDEN)) {
  // This runs in a hidden iframe - register your extension points
  import('./init-app.js');
} else {
  // This runs when a location is displayed - render your UI
  import('./render-location.js');
}
The Admin SDK uses two types of iframes:
  • Main Hidden: A hidden iframe where you register all extension points
  • Location iframes: Visible iframes that render UI for specific locations
4

Register Extension Points

Create init-app.js to register your extension points:
import { notification, ui } from '@shopware-ag/meteor-admin-sdk';

// Add a custom menu item
ui.menu.addMenuItem({
  label: 'My Custom App',
  locationId: 'my-custom-app-main',
  displaySearchBar: true,
});

// Add a card to the dashboard
ui.componentSection.add({
  component: 'card',
  positionId: 'sw-dashboard-index__content',
  props: {
    title: 'Welcome to My App',
    subtitle: 'Your first admin extension',
    locationId: 'my-dashboard-card'
  }
});

// Show a welcome notification
notification.dispatch({
  title: 'App Loaded',
  message: 'Your custom admin app is now active!',
  variant: 'success'
});
5

Render Location Content

Create render-location.js to handle different location views:
import { location } from '@shopware-ag/meteor-admin-sdk';

const currentLocation = location.get();
const app = document.getElementById('app');

// Define content for each location
const locationContent = {
  'my-custom-app-main': `
    <div style="padding: 20px;">
      <h1>My Custom App</h1>
      <p>Welcome to your custom admin application!</p>
    </div>
  `,
  'my-dashboard-card': `
    <div style="padding: 20px;">
      <p>This is a custom card on the dashboard.</p>
      <button onclick="alert('Hello from your app!')">Click Me</button>
    </div>
  `
};

// Render the content for the current location
if (locationContent[currentLocation]) {
  app.innerHTML = locationContent[currentLocation];
}
6

Create the App Manifest

To register your app with Shopware, create a manifest.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <meta>
    <name>MyAdminApp</name>
    <label>My Admin App</label>
    <description>My first Shopware admin app</description>
    <author>Your Name</author>
    <version>1.0.0</version>
    <license>MIT</license>
  </meta>

  <setup>
    <registrationUrl>http://localhost:8080/authorize</registrationUrl>
    <secret>your-secret-key</secret>
  </setup>

  <admin>
    <base-app-url>http://localhost:8080/index.html</base-app-url>
  </admin>

  <permissions>
    <read>product</read>
  </permissions>
</manifest>
Replace the URLs and secret with your actual development server configuration.
7

Run Your App

Start a local development server:
# Using Python
python -m http.server 8080

# Or using Node.js
npx http-server -p 8080
Then install your app in Shopware:
bin/console app:install MyAdminApp
bin/console app:activate MyAdminApp

​
Understanding the Code

​
Location Context

The Admin SDK uses different iframe contexts:
  • location.MAIN_HIDDEN: A hidden iframe that runs when the administration loads. This is where you register all your extension points (menu items, tabs, cards, etc.).
  • Location iframes: Visible iframes that display your actual UI components. Each location you define gets its own iframe.

​
Extension Points

You registered two types of extensions:
  1. Menu Item (ui.menu.addMenuItem): Adds an entry to the main navigation
  2. Component Section (ui.componentSection.add): Adds a card to an existing page position
Each extension has a locationId that identifies where your content should be rendered.

​
What’s Next?

Working with Data

Learn how to read and write Shopware entities

Custom Modules

Explore all available UI extension points

CMS Extensions

Create custom CMS elements for Shopping Experiences

Full Example App

Check out the complete example app in the repository

​
Troubleshooting

  • Verify your manifest.xml is correctly configured
  • Check that your development server is running
  • Ensure the app is installed and activated in Shopware
  • Check the browser console for any errors
  • Make sure your code runs in the MAIN_HIDDEN location
  • Verify that you’re importing the SDK correctly
  • Check that positionIds match existing admin positions
  • Confirm your locationId matches what you registered
  • Use location.get() to verify the current location
  • Check browser console for any JavaScript errors

Build docs developers (and LLMs) love

Get started for freeTalk to us