Customizing code

An advanced guide for developers on how to best extend Primavera code.

Primavera has been architected to be easy to extend by developers. The Primavera team has a combined experience of 10+ years working directly with merchants to customize existing themes, and we wanted to bring our knowledge to a theme. We will make continuous improvements to Primavera to add new theme sections, support new Shopify features and improve store loading performance.

Primavera utilizes browser technologies first, and we minimize the use of build tools in order to keep our source code easy to read. We do not use a framework for our CSS or JavaScript in order to make it as easy to extend as possible for developers.

Custom development is not covered by our support policy, and making customizations to key functionality may prevent us from being able to assist you with your theme.

Wherever possible, we advise merchants to avoid making changes in a way that will prevent these theme updates. Our support team cannot help with migrations that involve customizations to the theme code (which include Liquid, HTML, CSS or JS), meaning that a developer will likely need to be involved for every subsequent theme upgrade.

If you still do wish to make deeper customizations, we have some advice for how to do so in a way that will make the upgrade process smooth as possible.

Add custom CSS to the theme editor or a separate file

Don't modify the theme.css file directly, as it will become extremely difficult for future developers to track whether or not any changes have been made. For one off changes to individual sections or a small amount of tweaks to the global CSS, we suggest using the Custom CSS field in the theme customizer. Changes made to the CSS in the customizer can be carried forward across theme upgrades without the need for developer intervention.

The Shopify theme customizer offers a field for editing custom CSS

If your changes exceed the character count of these fields, we suggest you make a custom CSS file for the theme. This will allow you to easily port over all changes to an update by importing the CSS again on an updated theme. It will also give you a good overview of where you need to look in order to ensure the upgrade has completed successfully.

We strongly advise against modifying the theme.css or any other theme CSS files directly.

Create new sections if you are changing a section significantly

Instead of editing a section, create a new copy of that section and call it something like slidehow-custom.liquid. This will prevent merge conflicts between theme code and your custom code, and if you choose to upgrade the theme, you will be able to copy and paste the entire section directly instead of looking through what has changed.

Extend theme JavaScript instead of modifying it directly

Primavera uses Web Components/HTML Custom Elements for all key functionality. We don't recommend modifying the theme.js file directly, but any of our components can be extended by extending the web component. For example, if you needed to add additional behaviors to the product form, you can do so without touching the original code like in this example before:

class CustomProductForm extends ProductForm {
  constructor() {
    super();
  }

  onSubmitHandler(event) {
    // This calls all the original JavaScript
    super.onSubmitHandler()
    
    // Add your custom code here!
  }
  
customElements.define('custom-product-form', CustomProductForm);

Don't use apps that touch the theme code

Shopify has introduced an architecture called 'app blocks' that allow apps to be included without having to modify theme code. Utilizing app block architecture is the best way to ensure your app settings are carried forward with each theme update. Apps that use the legacy architecture may need to be reconfigured every time you update the theme.