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 1: Update Command (Recommended way)¶
Sulu is shipped with a build in command to update the build.
Run Update Build command
bin/adminconsole sulu:admin:update-build
Note
The update build command will download the build for your project from the sulu/skeleton repository if possible. If you have added custom Javascript code in your project, the command will automatically cleanup leftovers from previous builds and build the Javascript code manually on your system. Make sure that you have installed node if your project requires a manual build.
Solution 2: Build manually with docker¶
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
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
Create the administration interface build
cd /var/project/assets/admin
npm install
npm run build
Solution 3: Build manually locally¶
Install Node
If not yet installed on your computer you would need to install node on your computer.
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
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:
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..
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