Unlocking Shopware 6 Secrets: Master Building Administration Plugin Assets Without Wrecking the Core!

We are often phased with situations, where we actually have a hard time to figure out why certain things are suddenly broken just by running a simple command which is intended to be used to create for eg static build files.

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.