In this tutorial, you will learn how to avoid making some common architecture mistakes within a website powereed by Episerver CMS. One of the biggest challenges for developers new to CMS architecture, is a lack of information on what techniques work and what should be avoided. Most experienced CMS developers have learnt these lessons the hard way, through trial and error.

Over the years, I have worked on some really good projects. Sadly not all of the projects that I have worked on have been home runs. When trying to design a website with a flexible architecture, hindsight is a beautiful thing. Without learning from mistakes, you'll never design world-class solutions. In today's guide, you will learn some tips that will help you to avoid the most common Episerver architecture mistakes I have encountered on projects over the years. So if you want to save yourself from a load of headaches, read on 🔥🔥🔥

Never Modify The Episerver Database Schema

No matter how tempted you might be, NEVER manually modify the Episerver database schema yourself. If you think you need to change the schema, trust me, your approach is wrong. If you are convinced you need to change the schema, take a step back, breathe and think about the different options available to you.

Only ever access Episerver data via their APIs. If something is not working, raise a support ticket. Do not change the data in the database manually, or change the schema to make something work. Doing so, will cause you upgrade issues later on. If you need to store custom data, I recommend putting that data in a separate database, ideally accessed via an API. The Episerver database is not for developers to touch ❌

Forgetting Content Editors

One of the main aims of your job is to make an easy to use backend experience for content editors. People new to CMS tend to forget this. It is easy to focus on building the frontend features and to not give the poor content editor a second thought. As a business solution, if the people who will be using Episerver all day, every day, hate it.. then your project can never be considered a success. There are a number of things you can do to improve the content editing experience, these include:

The main takeaway is to consciously design a good blackened editor experience 🤔

Content Is King

When you launch a new project, you may only be working with a few pages. After a number of months and years, the amount of content contained within a website tends to increase rapidly. When this happens, the Episerver page tree can grow to unmanageable proportions. When the page tree becomes a mess, editors start to struggle to find content. In some extreme cases where the site tree contains thousands of pages under a single node, your site might even slow down to unusable levels. Common areas within the page tree where this type of content smell can occur are typically in areas where editors create blogs and news items.

To avoid this mess, use the [AvailableContentTypes] attribute. Restricting the types of pages an editor can create within the CMS will force editors to use a better content strategy. You should also make use of container page-types. Container pages can further restrict how content editors organise content within the page tree. More information about how to do this can be found here.

Search And Performance

In Episerver, it is possible to search for content using the FindPagesWithCriteria API. Whenever you use FindPagesWithCriteria it will query the database. There is NO caching when you use this. When you use FindPagesWithCriteria, you need to be careful that you don't overuse it. If you hammer the database to often your site's performance will be very bad.

When building a site search, consider using a third-party search provider, like Episerver Find, to help take the load off of your database. For more advice, I recommend reading this article.

Organising Your Blocks and Media Gallery

This issue is similar to the issues that you may encounter with unmanaged pages. The more blocks and images that are added within the CMS, the harder it will be to manage. I recommend that you organise the block and media folders before handing the project over to the content editors. Common ways to organise the block library include:

  • Alphabetic and numeric folder structure
  • Grouping the content into folders by language
  • Grouping the content into folders by departments, brands or products
  • Date, usually Year and subsets containing the 12 months
  • Grouping by usage (Buttons, Authentication, News, Blog etc..)

Pick the organisation system that makes you happy. The key takeaway is that you need to pick one!


So, there you have it. Delivering a successful project is not just about hitting a date, or, making a slick frontend. Building a product that is well made, where content editors can write content easily, all while helping a business to meet its objective has a lot of considerations.

A lot of the things listed in this article might sound basic, however, these are things developers new to CMS might not consider. I tend to find both content editors and marketers consider these tasks as essential considerations to make their day-to-day lives manageable. When building a project, talk to the content team to make sure they are happy 😊. Happy Coding 🤘