Overriding the Strapi Admin UI

1. Goal

My goal with this post is to detail the steps to customize or override the Strapi Admin UI functionalities for the projects that use Strapi v4.15.1 or later. If your Strapi version is prior to v4.15.1, this post details the steps.

2. Challenges with overriding Strapi Admin UI Functionalities

Starting with Strapi 4.15.1, whenever we add Strapi to a project, the node_modules/@strapi directory contains the compiled output JavaScript files instead of the source code files. For example, the files within the node_modules/@strapi/admin/dist/_chunks/ folder now contain the compiled output JavaScript files. As a result, the patch-package approach detailed in this post doesn’t work any more.

This means, we need to:

• Maintain the overrides / customizations code that we make on top of Strapi’s code elsewhere.
• Build the compiled output JavaScript files from the above.
• Replace the default output JavaScript files with these files.

3. Steps to override a Strapi Admin functionality

3.1. Setting things up

• For the purpose of this blog post, I created a demo project that uses Strapi v4.25.3. Our goal is to override the Strapi Admin UI feature within this setup.

• Also, we need a fork of Strapi v4 on github. This fork is the place where we shall code and maintain all our Strapi admin overrides / customizations going ahead. Here’s the fork I created.

3.2. Adding customization code changes

• To add our code customizations, we need to clone the forked repository locally. We then need to switch this Strapi source project to the exact same version used in my main Strapi project. My demo project uses Strapi v4.25.3. So, I find the commit for Strapi v4.25.3 here and run git checkout fc4f1a155faf953d74f6f9d78b63806eae084ab9 on my local.

• We shall now cut a branch from here to contain our changes on top of the identified Strapi version code. For my purpose, I cut the branch menu-changes-strapi-v-4.25.3 via the command git checkout -b menu-changes-strapi-v-4.25.3.

• For the purpose of this blog post, I modified Strapi’s left menu’s filtering capability (changed it to includes instead of contains). My code changes can be seen here. These changes reside in the branch menu-changes-strapi-v4.25.3. Similarly, you can make your changes to the Strapi Admin features source code and store them within a certain branch within your fork.

• Once the code changes are complete, we run yarn and yarn build to build the distributables. The compiled JavaScript output files get created within the packages/core/admin/dist folder. These are the compiled output files with our override changes in place.

3.3. Verifying our customizations

• To verify if our changes work well with our actual Strapi project, we now need to copy the just obtained JavaScript output files into our destination project. This means removing the node_modules/@strapi/admin/dist folder (from our actual Strapi project) and replacing it with the just obtained packages/core/admin/dist folder (from our Strapi source code project).

• Once the above is performed, we should be able to build our actual Strapi project and test for all our customizations / overrides to ensure they work as expected.

• Once the overrides are functionally verified, we need to automate the process of deploying our code customizations.

3.4. Automating the deployment of our customization changes

• We can setup installing our customization changes as a postinstall step. For this to work, we need to copy the generated JavaScript output files into a separate folder within our actual Strapi project. In my demo project, I did so at strapi_admin_override_files/admin/distributable folder.

• We also need to create a shell script that can remove the original dist folder and copy these overriden output files. I did so via the copy_distribution_files.sh script file.

#! /bin/bash
echo "Removing node_modules/@strapi/admin/dist"
rm -rf node_modules/@strapi/admin/dist
echo "Copying strapi_admin_override_files/admin/distributable"
cp -R strapi_admin_override_files/admin/distributable node_modules/@strapi/admin/
mv node_modules/@strapi/admin/distributable node_modules/@strapi/admin/dist

• Lastly, adding the just created shell script as a postinstall step ensures all of this is performed automatically after packages are installed.

"postinstall": "./strapi_admin_override_files/copy_distribution_files.sh"

• With the above setup, every time yarn or npm install is performed, the default packages would be installed and our JavaScript output files will then be copied on top of the default packages.

Future Strapi Upgrades

With the above detailed setup in place, every time we decide to upgrade our setup’s Strapi version, we need to:

• Sync our fork to the upstream strapi repository.
• Cut a new branch from the specific Strapi version we are upgrading to.
• Perform the override code changes in this new breanch.
• Generate the output JavaScript files and start maintaining them in our project repository.

While this is a hassle, given that Strapi now ships only compiled code, this appears to be the only reliable way to override Strapi admin functionalities going ahead.

Punit Sethi

My tryst with Strapi:

Back in mid-2021, one of my clients was having issues with their in-house CMS. Despite me being their frontend architect, they trusted me to build their CMS solution. At this point, evaluation of various frameworks, approaches and products led me to Strapi. And, I ended up implementing Strapi CMS for their data requirements.

Fast-forward to now, I have worked with multiple orgs on implementing, upgrading & customizing Strapi setups based on their requirements.

Read my other posts on customizing Strapi.