Building the administration interface frontend application

The administration interface of Sulu is implemented as a single page application using React. The code of this application is built using webpack and stored in the public/build/admin directory of the project. If you update your Sulu version or add custom Javascript code to your project, you need to update the build in the public/build/admin directory. There are different ways to do this:

Solution 2: Build manually with docker

  1. Start a node container with the desired version and map the the current directory into the /var/project folder in the container
docker run --rm --interactive --tty --volume ${PWD}:/var/project node:14.16.0 /bin/bash

# for completion: using another node version is possible by adjusting the tag of the node image
# docker run --rm --interactive --tty --volume ${PWD}:/var/project node:12.21.0 /bin/bash
  1. Cleanup previously created node_modules folders and package-lock.json files
cd /var/project
rm -rf assets/admin/node_modules && rm -rf vendor/sulu/sulu/node_modules && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/node_modules
rm -rf assets/admin/package-lock.json && rm -rf vendor/sulu/sulu/package-lock.json && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/package-lock.json
  1. Create the administration interface build
cd /var/project/assets/admin
npm install
npm run build

Solution 3: Build manually locally

  1. Install Node

If not yet installed on your computer you would need to install node on your computer.

  1. Cleanup previously created node_modules folders and package-lock.json files
cd /var/project
rm -rf assets/admin/node_modules && rm -rf vendor/sulu/sulu/node_modules && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/node_modules
rm -rf assets/admin/package-lock.json && rm -rf vendor/sulu/sulu/package-lock.json && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/package-lock.json
  1. Create the administration interface build
cd /var/project/assets/admin
npm install
npm run build

Common errors

If the installation of the npm dependencies or the webpack build fails, you might want to try the following things:

  1. Check your Node.js and npm version

You can check the officially supported and tested Node.js and npm version by looking at the Test Application workflow of the sulu/sulu package. At the time of writing, this includes Node.js 12, Node.js 14 and npm 6.

Warning

Because of a breaking change for linked packages, Sulu is not compatible with npm v7 at the moment. Have a look at the issue in the sulu/skeleton repository for more information about this..

  1. Clear the npm cache on your machine

The webpack build might fail because of leftovers from previous builds our outdated packages. To prevent this, you should remove all the package-lock.json files and node_modules directories below your project root before installing the npm dependencies:

rm -rf assets/admin/node_modules && rm -rf vendor/sulu/sulu/node_modules && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/node_modules
rm -rf assets/admin/package-lock.json && rm -rf vendor/sulu/sulu/package-lock.json && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/package-lock.json

If this does not solve the problem, you can try to clean the npm cache on your machine to prevent installing cached packages:

npm cache clean --force