I know that this guide is not bulletproof regarding update safety, because each Shopware core update will overwrite the changes. But you have to keep in mind that it is also hard for Shopware to maintain different development environments. I'm pretty sure Shopware will add a fix if there is time left to implement it, because as you will see, there is not much to change to make it work with DDEV.

So let's jump right into it.

The Problem

There is an issue on GitHub titled Vite watch administration not loading plugin modules, which outlines the problem developers face when using DDEV with Shopware 6.7's Vite-based administration. In short, each plugin (or extension) starts its own Vite dev server. However, because DDEV uses the ddev-router in the background, this setup does not work out of the box.

If you try to use the admin watcher without applying the necessary changes, you will encounter errors such as:

Of course, the administration is still working but your plugins (or extensions) will not get injected.

The root cause is that DDEV cannot map or, more accurately, does not allow access to the ports used by the Vite dev servers. To resolve this, you need to apply the changes described in this guide.

Changes in plugins.vite.ts

On line 184, there is the extensionEntries config starting. Within the forEach loop change this

from

// vendor/shopware/administration/Resources/app/administration/build/plugins.vite.ts

if (extension.isApp) {
    swPluginDevJsonData[extension.technicalName].html = `http://${host}:${availablePorts[index]}/index.html`;
}

if (extension.isPlugin) {
    swPluginDevJsonData[extension.technicalName].js = `http://${host}:${availablePorts[index]}/${fileName}`;
    swPluginDevJsonData[extension.technicalName].hmrSrc = `http://${host}:${availablePorts[index]}/@vite/client`;
}

to

// vendor/shopware/administration/Resources/app/administration/build/plugins.vite.ts

const realHost = process.env.DDEV_PRIMARY_URL
              ? `${process.env.DDEV_PRIMARY_URL.replace(/:\d+$/, '')}`
              : `http://${host}`;

if (extension.isApp) {
    swPluginDevJsonData[extension.technicalName].html = `${realHost}:${availablePorts[index]}/index.html`;
}

if (extension.isPlugin) {
    swPluginDevJsonData[extension.technicalName].js = `${realHost}:${availablePorts[index]}/${fileName}`;
    swPluginDevJsonData[extension.technicalName].hmrSrc = `${realHost}:${availablePorts[index]}/@vite/client`;
}

Afterwards, change the server config for app and the plugin system.

Add const host = '0.0.0.0'; within the loop for (let i = 0; i < extensionEntries.length; i++) to make it accessible via the host machine.

// vendor/shopware/administration/Resources/app/administration/build/plugins.vite.ts

// Start dev servers
 for (let i = 0; i < extensionEntries.length; i++) {
    const host = '0.0.0.0';
    // ... rest of code
}

Next, search for createServer and replace from

// vendor/shopware/administration/Resources/app/administration/build/plugins.vite.ts

server: {
    port,
    host,
    cors: true,
},

to

// vendor/shopware/administration/Resources/app/administration/build/plugins.vite.ts

server: {
    port,
    host,
    origin: process.env.DDEV_PRIMARY_URL
        ? `${process.env.DDEV_PRIMARY_URL.replace(/:\d+$/, '')}:` + port
        : undefined,
    cors: {
        origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
    },
},

Changes in vite.config.mts

Add the cors config to the server config which starts at line 65 and add it after the origin property.

// vendor/shopware/administration/Resources/app/administration/vite.config.mts

cors: {
    origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
},

Changes in the .env file

Add a entry for host like

HOST=0.0.0.0

Changes in .ddev/config.yaml

In order to expose all needed ports, there has to be an entry for each port. From my experience, it is sufficient to expose the ports 5173-5400. Each plugin will get its own dev server starting at port 5333. Because DDEV does not support port ranges natively in config.yaml, we have to define each port separately.

You can create the entries with this bash script:

for i in $(seq 5173 5400); do
  echo "- name: webdev-dev-server-admin-port-$i"
  echo "  container_port: $i"
  echo "  http_port: $(((i-1)*10))"
  echo "  https_port: $i"
done > /path/to/file/ports.txt

Next, take the contents of the generated ports.txt file and add them to your ./ddev/config.yaml file. Look for the commented line containing web_extra_exposed_ports—this is where you should insert the port entries to keep the configuration organized.

Finally, restart your DDEV project with:

ddev restart

You should now be able to use the admin watcher by running

ddev exec ./bin/watch-administration.sh

Summary

By following the steps above, you can successfully configure Shopware 6.7's Admin Watcher to work seamlessly with DDEV. The adjustments ensure that hot module reloading and plugin development work reliably in your local environment. While these changes may need to be reapplied after Shopware updates, they provide a practical solution for efficient development workflows with DDEV and Shopware 6.7 for extensions within the administration.

Let me know if it worked for you, or if you found anything that could be improved.

So was I while talking with friends about a weird behavior which they encountered after running

./bin/build-administration.sh

This command - which I thought should get executed after a shopware update - seems not to be what I thought it would be. I mean, it did and does what it should on my side but broke the administration for them.

Going down the rabbit hole

./bin/build-administration.sh

This little shell script does actually nothing special. It just goes through all directories, npm clean installs all dependencies (and also all dev-dependencies) for the plugins which you have installed and activated and also the shopware administration core.

The key takeaway from here is, that the resolve process of installing the plugin dependencies happens through webpack which is configured with a webpack.config.js file in the administration core codebase.

But, running this command on production means a few things

1. Downtime/not working administration as long as all npm packages get installed and the final build is finished

2. Your Plugin administration assets get build

3. The core administration files get build again as well although there should be no changes (as long as you didn't update anything manually which you should never do 😅)

What's wrong with using it in production?

First, the official shopware docs do not mention node js as requirement, it is optional. You might have installed it for any reason (who did not build something in production because something else is broken, we know it right? 😅) but you don't have to.

Second, building the entire administration core Javascript/Typescript/Scss code can be time consuming especially if it is not needed nor intended that we do it at all. The Shopware administration repo has all build files already committed into the repository. You get the updated build files while updating shopware anyway for free.

Third, why should we risk a downtime although it might not be necessary at all?

How should it be done then?

Good question, you can still stick to the ./bin/build-administration.sh shell script but, you should use it with a additional env variable. The right command would be

SHOPWARE_ADMIN_BUILD_ONLY_EXTENSIONS='1' ./bin/build-administration.sh

This env variable is used in the webpack.config.js file of the administration core. Once it is set, the administration core code doesn't get touched at all but only your installed and activated plugins will get build.

Another way of building the static files for the administration is mentioned in the next section.

Is there a easier way to build static files for administration?

The easiest way to make sure all build files are in the plugin directory (no matter if self developed or installed from the shopware community store) is by using the build command which I mentioned above or by using the shopware-cli from FriendsOfShopware.

This cli tool makes sure, that only necessary files land in the build. This means, no dev dependencies, just the code which you need for production.

Once installed, you can simply run in your Shopware root

shopware-cli extension build custom/plugins/PLUGIN_NAME

This will install all necessary dependencies and bundle the files for the administration of the plugin.

But how does it work with plugins which I install from the store?

This was the question which I asked myself. There are specific requirements for a plugin to be available in the store.

One of those requirements is, everything is bundled up into one zip file. I won't talk about each necessary file but one part of this zip file are the static build files, the bundled js and css files, which reside in YourPlugin/src/Resources/public/administration.

After installing and activating a new plugin from the shopware community store, a PHP service gets called which in fact does the same thing as

bin/console assets:install

to copy all the files and make them available to get called from the administration logic.

How should I proceed then? Need that thing on production shipped 🚀

It depends on the environment where you do all of the build steps.

Let's take a look about three of them because doing it on production servers should be the very last environment where you should do it. Consider it not recommended, but it will also work there.

Development Environment

If you simply want to do it with one plugin, you can run the command which you already saw above by using the shopware-cli

shopware-cli extension build custom/plugins/PLUGIN_NAME

If you want to build all static assets of all locally installed plugins, then you can use a little shell script

cd /plugins
for dir in */ ; do \
    echo "Running shopware-cli extension \ build for ${dir}..." \
    shopware-cli extension build "${dir}" \
done

You will recognize, that this is not the best way because the shopware-cli will fetch the shopware core code for each plugin. This command builds not only the administration code but also your storefront code

A better way to build all static assets for administration only will be to run the project build command in the root of your shopware instance.

shopware-cli project admin-build

This does essentially the same as ./bin/build-administration.sh except of leaving all of the shopware core asset builds untouched.

CI/CD

The best idea of course is always to use a CI/CD for managing builds and deployments.

You can use the same commands as mentioned in the Development Environment section. It depends on which CI/CD Service you are using but the project admin-build command will need a entire shopware instance. To achive this, you can use a docker container from FriendsOfShopware.

Production (not recommended ☝🏻)

If nothing else is possible anymore and the production version of your shopware store seems to be broken and you know it is because of new code which might not get loaded properly, then you can try to build the administration to make it full functioning again.

But you should only do it, if you are sure that it is related to a plugin which worked before. Also double check if the build files of the plugin are there where they should be.

If they are missing, then you can try to build them again with

SHOPWARE_ADMIN_BUILD_ONLY_EXTENSIONS='1

Or if you have the shopware-cli installed on production as well with

shopware-cli extension build custom/plugins/PLUGIN_NAME

If you are using the shopware-cli, then you have to execute another command afterwards to get the build files copied to

<ShopwareRoot>public/bundles/PLUGIN_NAME/administration

The command which you have to execute is

bin/console assets:install

After running it, you should find the static files of the plugin for the administration in the mentioned public/bundles directory.

Conclusion

Shopwares static file build system for the administration is a solid and well organized pipeline of tools to enable a easy to use process if used right. By enhancing this process with using the right environmental variables or the shopware-cli - which was build from one of Shopwares core development members - you can go even further which will reduce the build time on one hand and makes sure that you don't build files which already exist or even break them.

I use the shopware-cli in a CI/CD pipeline via github actions myself for our staging, testing and production environments for 0815.at to build all static files (not just the administration static files) and to deploy them.

It is not only the best option performance wise, but also the safest way to not break working shopware production core code.