---
title: Theme best practices | Shopware Community Hub
description: >-
  Learn about the art of developing robust and maintainable themes in Shopware.
  Learn essential practices for responsive design, SEO optimization, SCSS…
canonical_url: 'https://hub.shopware.com/learn/unit/solutions-architect-theme-best-practices'
---

# Theme best practices

<LearningObjectives>

- Understand the **essential practices** for developing and maintaining themes in Shopware.
- Implement **responsive and SEO-friendly designs** that enhance the user experience and improve shop visibility.
- Use **structured and modular SCSS, custom templates, and Shopware blocks** to create themes that are maintainable and compatible with future updates.
- Optimize **theme performance** and leverage plugins to extend functionality effectively.
- Correctly manage **Twig template** overrides to ensure proper functionality and avoid conflicts.
- Utilize **testing tools** to ensure theme quality, performance, and SEO compliance.

</LearningObjectives>

# Theme Development in Shopware

Developing a theme in Shopware involves more than just aesthetics; it requires careful planning and adherence to best practices to ensure that the theme is robust, scalable, and future-proof. This unit will guide you through the key principles and techniques you should follow when developing a theme in Shopware 6.

## 1. Understand the Shopware Theme Structure

Before diving into theme development, it's crucial to familiarize yourself with the Shopware theme structure. The theme directory is organized into various folders, each serving a specific purpose. Key components include:

- **Templates**: The backbone of your theme, where the HTML structure is defined.

- **Styles (SCSS)**: Contains all the SCSS files responsible for styling your theme.

- **JavaScript**: Houses scripts that add interactivity and enhance user experience.

- **Assets**: Includes images, fonts, and other static resources used throughout the theme.

```text
# structure of a plugin-based theme
├── composer.json
└── src
├── Resources
│   ├── app
│   │   └── storefront
│   │       ├── dist
│   │       │   └── storefront
│   │       │       └── js
│   │       │           └── swag-basic-example-theme.js
│   │       └── src
│   │           ├── assets
│   │           ├── main.js
│   │           └── scss
│   │               ├── base.scss
│   │               └── overrides.scss
│   └── theme.json
└── SwagBasicExampleTheme.php
```

Understanding how these components interact will help you navigate the theme more efficiently, troubleshoot issues, and maintain a clean and organized codebase.

## 2. Responsive Design and Mobile Optimization

In today’s mobile-first world, ensuring that your theme is responsive and optimized for mobile devices is non-negotiable. Implementing responsive design principles allows your shop to adapt seamlessly across different screen sizes, providing a consistent user experience regardless of the device.

- **Fluid Grids**: Use fluid grids to create flexible layouts that adjust dynamically to different screen sizes.

- **Touch-Friendly Elements**: Prioritize touch-friendly design, ensuring that buttons, links, and interactive elements are easy to tap on smaller screens.

- **Viewport Meta Tag**: Always include the viewport meta tag in your templates to control layout scaling and improve the mobile browsing experience.

## 3. SEO Compatibility

SEO is a critical aspect of theme development, as it directly impacts your shop’s visibility in search engines. To optimize your theme for SEO:

- **Schema Markup**: Implement structured data using schema markup to help search engines understand your content better.

- **Clean URL Structures**: Ensure your theme supports clean, SEO-friendly URLs that are easy for search engines to crawl.

- **Meta Tags and Open Graph**: Integrate meta tags and Open Graph data to improve your pages' appearance in search results and social media sharing.

Read more: [Shopware SEO Settings](https://docs.shopware.com/en/shopware-6-en/settings/seo).

## 4. Use Structured and Modular SCSS Code

When writing SCSS, it's essential to maintain a structured and modular approach. This practice not only makes your code easier to read and maintain but also enhances collaboration when multiple developers are working on the same theme.

- **Modular SCSS Files**: Break down your SCSS into smaller, manageable files based on components, layouts, and themes.

- **Variables and Mixins**: Use variables for colors, fonts, and other recurring elements, and create mixins for reusable styles. This approach ensures consistency and simplifies updates across your theme.

## 5. Create and Register Custom Templates

Custom templates allow you to make changes to your theme without altering the core code, ensuring that your modifications are preserved during updates.

- **Custom Template Files**: Create custom template files for specific site sections, such as the header, footer, or product listings.

- **Template Inheritance**: Leverage Shopware’s template inheritance system to extend or override existing templates without modifying the core files.

Read more: [Customize Templates](https://developer.shopware.com/docs/guides/plugins/plugins/storefront/customize-templates.html).

## 6. Use Shopware Blocks

Shopware blocks provide a powerful way to modify templates without directly editing the core files. This approach ensures that your theme remains compatible with future Shopware updates.

- **Extend or Override Blocks**: Instead of altering the original template, use Shopware blocks to extend or override specific sections of the template. This method protects your customizations from being overwritten during updates.

- **Block Naming Conventions**: Adhere to Shopware’s block naming conventions to maintain clarity and consistency in your codebase.

## 7. Twig Template Overrides: Best Practices

When working with Twig templates, it's important to understand the order in which template files are loaded and how to manage overrides properly. Here are the best practices:

- **Correct Placement of Overrides**: Overrides can be placed in either the Theme views directory or the Extension views directory. However, to avoid conflicts and ensure that your overrides work correctly, it’s crucial to understand the loading order:

    - **Default Order**: By default, the loading order is `Shopware core > Extensions > Theme`. This means that any overrides in your theme will take precedence over those in extensions.

    - **Modifying the Order**: You can change this order by configuring the `theme.json` file, specifying certain plugins to load after your theme. This should be done sparingly and typically indicates a need to revisit how you’re managing overrides.

**Avoid Full File Overrides**: Do not override the necessary parts of a template. Rather than copying the entire file, only override the necessary parts. This minimizes the risk of conflicts and ensures better compatibility with future updates.

- **Use the Parent Call**: Always use <code v-pre>{{ parent() }}</code> where possible to maintain the structure of the original template. This ensures that your overrides add functionality without disrupting the core structure.

## 8. Optimize Performance

Performance is a crucial factor in both user experience and SEO rankings. To ensure your theme loads quickly:

- **Minimize HTTP Requests**: Reduce the number of HTTP requests by combining CSS and JavaScript files where possible.

- **Leverage Caching**: Implement caching strategies to store static resources, reducing load times for returning visitors.

- **Optimize Images**: Compress images and use modern formats like WebP to reduce file sizes without sacrificing quality.

## 9. Testing and Debugging

Thorough testing and debugging are essential to ensure that your theme works correctly across different browsers and devices. Here are some best practices for testing and debugging your Shopware theme:

- **Cross-Browser Testing**: Test your theme in all major browsers to ensure compatibility and consistent behavior.

- **Device Testing**: Use emulators and real devices to test your theme on different screen sizes and resolutions.

- **Debugging Tools**: Utilize debugging tools such as browser developer tools to identify and fix issues efficiently.

### Testing Tools

- **[Schema Markup Validator](http://schema.org)**: Use this tool to validate the structured data on your homepage, category pages, and product detail pages. This helps ensure that your site’s schema markup is correctly implemented, improving SEO and search engine visibility.

**Google Lighthouse**: Run a Lighthouse audit to evaluate the performance, accessibility, best practices, and SEO of your frontend. When applying changes, there should be no significant regressions in performance or accessibility scores.

- **Debug Console**: Test the frontend and checkout processes using the browser’s debug console. Please pay special attention to new JavaScript errors, as they can negatively impact the user experience.

### Testing Scenarios

- **Homepage and Category Pages**: Use [http://schema.org](http://schema.org) 's Structured Data Testing Tool to check the homepage and category pages for structured data issues.

- **Product Detail Pages**: Test various product detail page configurations (e.g., available products, unavailable products, products with and without reviews, out-of-stock products, products to be released in the future) for structured data integrity.

- **Shopping Cart and Checkout**: Ensure that customizations do not interfere with the price and shopping cart button. The shopping cart button must always be clickable and functional.

## 10. Leverage Plugins

Plugins can significantly enhance the functionality of your theme, allowing you to add new features without extensive development.

- **Reputable Plugins**: Choose plugins that are regularly updated and have good reviews to ensure compatibility and security.

- **Theme Compatibility**: Always test plugins with your theme to ensure they work seamlessly and do not cause conflicts.

## 11. Follow Shopware’s Best Practices

Adhering to Shopware’s official documentation and best practices is key to ensuring that your theme is future-proof and compatible with Shopware updates.

- **Stay Updated**: Regularly check Shopware’s documentation and community forums for updates and best practices.

- **Code Quality**: Maintain high code quality by following coding standards and guidelines provided by Shopware. Consider using one or more of the following linters in your IDE or build pipeline:

    - **Twig Files**

        - **Ludtwig**: A linter and formatter for Twig template files that respects HTML structure and focuses on developer productivity. Ludtwig is used by the Shopware core and validates Twig syntax using configurable rules.

        - **TwigCS**: A coding standard tool for Twig templates. It can be used as an alternative to enforce consistent formatting and best practices across Twig files.

    - **SCSS Files**

        - **Stylelint**: A powerful linter for CSS, SCSS, and other CSS preprocessors. It checks for syntax errors, enforce coding styles, and flags potential issues in your stylesheets.

    - **JavaScript Files**

        - **ESLint**: The most widely used JavaScript linter. It is highly configurable and can enforce a variety of coding standards and best practices. It can also be extended with plugins to support different frameworks and environments.

    - **VueJS Files**

        - **ESLint with Vue.js plugin (eslint-plugin-vue)**: ESLint can be extended with the Vue.js plugin to lint Vue components (.vue files). This combination helps in maintaining code quality in Vue.js applications.

            **Vetur**: While not a linter per se, Vetur is a VS Code extension that provides syntax highlighting, IntelliSense, and linting support for Vue files. It integrates with ESLint to provide linting capabilities.

## Conclusion

Developing a theme for Shopware requires a balanced approach that considers aesthetics, functionality, and performance. By following these best practices, you can create a theme that not only looks great but also provides a seamless and optimized user experience. Whether you’re working with SCSS, templates, or plugins, adhering to these guidelines will ensure that your theme remains maintainable, scalable, and compatible with future Shopware updates.