HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Project recommendations

Describes recommendations for implementing Optimizely Customized Commerce solutions.

The recommendations are based on common scenarios and input from implementation projects.

General recommendations

These guidelines aim to ensure stability and the best possible performance for your Optimizely Customized Commerce implementation. Most projects, especially first-time projects done by development teams with limited Commerce experience, should follow recommendations to avoid mistakes, technical debt, and performance and scalability issues.

Before making any exceptions from implementation recommendations, ensure you have a solid understanding of the underlying framework. Deviating from the recommended way of doing things may create more work than necessary and make future upgrades more difficult. See the Optimizely Customized Commerce system overview to learn more about the Customized Commerce framework.


Plan project carefully

Customized Commerce projects often take longer than originally estimated due to the pricing complexity, external integrations, and shipping and payment providers. Allow enough time for planning and design, and start small. Especially for first-time complex projects, it is recommended to do a proof-of-concept first with a complete order process in place.

Document code changes

When altering workflows or other downloadable code added to your solution, make it a habit to comment and document the code in the project. Well-documented code maintained in separated modules makes future system upgrades much easier.

Spend time on catalog design

Start early with the catalog modeling because this can be complex and often requires more design than originally realized. Let the website catalog hierarchy guide your catalog structure, and limit the number of variants/SKUs associated with each product to avoid performance implications.

See Guidelines for working with catalogs for information about catalog modeling.

Use the search API

The built-in search API is useful, especially for category landing pages and large catalog structures. It ensures better website performance, offloads database search and retrieval procedures, and provides paging and facets functionality. See Search.

Set search options correctly

The meta-field/model field search options are often misunderstood and misused. Two typical examples are:

  • Tokenize. This is often overused, even for fields that do not need to be searchable.
  • IncludeValuesInSearchResults. Overuse of this adds unnecessary bulk to the search index.

Turn on catalog caching

You should have a clear strategy for caching. Turn catalog caching on, or implement your own solution. Consider this especially for pricing and warehouse and inventory updates. See Caching.

Understand StoreHelper and CartHelper

Store helpers are useful, but you must understand how they work before using them. You can download helper classes here (requires login). These can be modified to suit your needs, for instance, by adding caching and other logic. For example, the StoreHelper has no pricing caching, so this needs to be added.

Other limitations to helper implementations are, for instance, that CartHelper does not allow a variant/SKU to be added multiple times as multiple line items. Regarding ownership of business logic, for StoreHelper use the ReadOnlyPricingLoader instead. For CartHelper, download the code and make it "your own."

Use the payment and shipment provider models

When implementing payment processing and shipping rate calculation, use the provider model. This makes them available in Customized Commerce and includes storage for configuration settings. See Payments.

Avoid database modifications

Modifying the database includes editing or deleting database tables and stored procedures. This can break functionality and prevent future upgrades.

Minimize use of MetaImage

The MetaImage metafield is used for storing images. Using this meta-field type in catalog meta-classes works for smaller, low-traffic websites but is inefficient for larger websites as the output is stored in the database. Also, it is not accessible outside of an entry. However, the MetaImage meta-field performance was improved recently.

Avoid excessive loading of content

For example, avoid using GetDescendents to load everything recursively and then filter by something to find what you were looking for.

With complex solutions, where code is scattered across multiple components, it may be difficult to see how your system loads content excessively. Everything on its own might look reasonable, but when those processes are combined, looped, and repeatedly requested under load with a large content set, you may have problems.

In many cases, you can resolve this by doing the following:

  • Analyzing what content is loaded and where, possibly using caching of aggregates, etc.
  • Using Optimizely Search & Navigation or another search index.
  • Possibly restructuring your content models or changing your content structure.

There is no "one size fits all" recipe to avoid excessive content loading. And you should not optimize prematurely. Think about your actions and how they might react in a production environment with a bigger content structure and underload.

In addition, it is good practice to profile the application, even without evidence of performance problems. This is recommended even if the Content Management System is installed on a dev machine with no real load and runs along certain central routes/code paths. Finding something in the code that is easy to fix and makes the application 30% faster is a good feeling and value even if the application runs acceptably in the production environment.