The Background

Today started with what should have been a simple task: adding a new navigation item to the merchant portal in Spryker. A small change, a quick refresh, and we’re done—at least, that’s what we thought. But things are never that easy, are they?

Like any sensible developer, we headed straight to the config/Zed/navigation-main-merchant-portal.xml file, added the new item, refreshed the page... and nothing happened. No new item in sight. If only things worked like they used to, where a simple file update immediately reflected in the UI. But modern caching systems had other plans.

The Investigation

Since our change didn’t show up, the first suspect was caching. We spotted a console command, navigation:cache:remove, and thought, “This has to be it!” But after running it, the navigation was still stuck in its old ways.

Next up: navigation:build-cache. Maybe the problem wasn’t clearing the cache, but rebuilding it? Nope. That command also didn’t work.

At this point, frustration started creeping in. A deeper look revealed the issue: these commands only work for Zed, not the merchant portal. But how were we supposed to know that? A zed: prefix would have saved us time and confusion. Instead, we were left wondering why a supposedly universal cache command had no effect on the merchant portal.

The Breakthrough

Since the commands didn’t work, we decided to go the manual route. Deleting the navigation-main-merchant-portal.cache file directly did the trick! The new navigation item finally appeared in the portal. But this wasn’t a sustainable solution—there had to be a better way.

Enter the hero of the day: console cache:empty-all. One simple command, and all caches from all modules were wiped clean. Just like that, the merchant portal navigation was updated, and we could finally move on.

Lessons Learned

Not all cache commands work where you expect them to. Always check the scope.

Spryker’s cache system can be misleading—commands like navigation:cache:remove and navigation:build-cache only apply to Zed, not the merchant portal.

Sometimes, the quickest fix is manual deletion, but an all-in-one command like console cache:empty-all is a lifesaver.

A little naming clarity (like adding a zed: prefix) could make a world of difference for developers.

At the end of the day, we finally got our navigation item to show up. It took longer than expected, but at least now we know the right way to handle navigation caching in the Spryker merchant portal. If you run into the same problem—skip the unnecessary steps and go straight for console cache:empty-all.

Happy coding!