Building your own Magento 2 starter theme

After having worked on a few Magento 2 projects we've discovered that we've been repeating the same tasks over and over at the start of each project. Removing redundant navigation elements, changing header layout or including our handy LESS mixins are only a few of those tasks that we constantly had to struggle with.

While we love Magento UI library and find it absolutely indispensible when it comes to customizing user interface, for us it still lacks some functionality that we otherwise have to to port over from our older projects.

For that reason we've decided to create our own starter theme that would help us kickstart our future projects. Below we explain the build process of creating our RW Prime theme.

TL;DR: If you're not interested in the build process but rather want to try one yourself you can skip ahead to the Installation section below that will guide you through a quick setup.

Requirements

Before starting the build process we first had to decide on what exactly we wanted to create. We've come up with a list of requirements for this theme:

It would have to be based on Magento Blank theme - we needed to create something quickly and efficiently, in between projects - Magento Blank was a perfect candidate for a foundation for our theme as we already knew it inside and out
It needed to utilize Magento UI library - we needed to have access to all of those handy mixins and variables Magento ships with but also needed a way to extend them
We would focus on adding functionaity not styling - we needed a boilerplate or a starting point for a project, not a full fledged theme where it's difficult to make even small CSS adjustments. We didn't care about the look but how easy it would be to customize
We would include only the most common modifications that we make on the majority of our projects - no point in bringing something over that won't be used and will only complicate development
It would have to be easy to install and upgrade - composer package was a no-brainer since the majority of Magento modules are distributed this way
It would have to easy to pick up and extend

The process

Modyfing template structure

It quickly become apparent that aside from the theme we'll need to a build separate module that will hold all custom logic needed to support our theme (blocks, helpers, widgets, etc.). We've created one and called it UiCore.

Once we had the module ready and tested we started working on our custom theme - imported all the necessary initialization files (theme.xml, registration.php and commposer.json), added preview image and some github related files. At this point theme was ready to be installed and activated on any envronment. Of course it didn't include any changes so it was essentially a clone of the Blank theme but we could finally start customizing our theme.

We started with layout - imported Magento_Theme/layout/default.xml and started removing redundant elements. Then we got to header and footer modifications (changed layout, moved things around, added a dropdown for My Account options) and moved on to mobile navigation changes. We completely referactored mobile menu, making it more accessible and easier to use. Once we got that out of the way we shifted our attention to the major pages - category, PDP and cart/checkout.

Styling enhancements

Once we had template structure modifications out of the way we moved to enhancing the presentation layer by including a couple of useful LESS partials we extracted from our past projects. We placed them all in our custom web/css/prime folder and imported in prime.less file along with Magento UI library.

While we've made a couple of styling changes with respect to Magento Blank theme we didn't want to go too deep with our customizations so it'll be easier to work with in child themes. We kept the modifications to a minimum preserving about 95% of original base styles and adding a bunch of mixins and helpful layout/utility classes. We also included our custom icon font for a good measure.

To facilitate customizing the theme we included a style guide page (by default located at your-project-url/ui), which helps preview changes to common UI elements (headings, buttons, tables, forms etc.) instantly.

Custom Javascript

While we didn't introduce a lot of custom scripts, the ones that we imported are pretty useful as we use them on regular basis (lazysizes, sticky header). Additionally, we included a general script prime.js for quick behavior enhancements.

We've also made a significant refactoring of one of our favourite modules for product and banner caorusels - WeltPixel_OwlCarouselSlider. We focused on replacing owlCarousel jQuery widget with Slick. We just find faster and more flexible than owlCarousel.

Delivery

Once we had all theme files ready and we were happy with the final result for our initial release we had to package and publish both our UiCore module and the Prime theme so their easy to distribute, install and upgrade. For that purpose we used Composer package manager.

We host our files on GitHub so they're publicly accessible. To create Composer packages we included composer.json files in the root folder of the module and the theme with all the relevant information needed to register them as packages.

Next, we submitted them to Packagist and connected with our GH repos. Once they synced they were ready to be distributed using composer CLI.

That's really all you need to create your own started theme that can be easily extended and distributed. In the next steps we explain how to install and use our Prime to allow you test and hopefully be inspired by our creation.

Installation

Ok, feeling convinced to give it a shot yet? Great! Below we're explaing the easiest way to install the theme on your local project.

Install using Composer

$ composer require rocketweb/theme-frontend-prime

Theme comes bundled with two modules: UiCore and CheckoutEnhancement. You'll need to install them using Magento CLI:

$ bin/magento module:enable RocketWeb_UiCore
$ bin/magento module:enable RocketWeb_CheckoutEnhancement
$ bin/magento setup:upgrade

To test if the theme has been installed correctly you can go to Admin > Content > Design > Themes. You should see RocketWeb/prime as one of the available themes.

Manual installation

If for some reason you don't want to use composer to install the theme you can always do it in a more traditional way by downloading a zip file from GitHub and extracting it in RocketWeb/prime theme directory in your project. Note that you'll need to take care of upgrading the theme manually then.

Make sure to also grab RocketWeb_UiCore module from another of our repositories, otherwise you won't be able to use some of the theme's features.

Usage

To start working with the Prime theme make sure to create your own custom theme that inherits from RocketWeb/prime. You can put all of your customizations in there but make sure not to modify the Prime theme files as your changes will be wiped out when the theme is updated.

Here's a sample theme.xml file for your own theme:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/Config/etc/theme.xsd">
    <title>Your Own Theme</title>
    <parent>RocketWeb/prime</parent>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

Documentation

You can find theme documentation in project's wiki on GitHub: https://github.com/rocketweb-fed/magento2-theme-prime/wiki

Collaboration

This theme is in constant development. If you want to contribute by fixing bugs or adding new features use our GitHub repo. Just fork the repository, push your changes and create a PR. Once your submission is reviewed and accepted we'll merge it to our develop branch and ship with the next release.

Conclusion

We hope you'll give it a shot and find our theme useful in your development or that perhaps it will help you create your own starter theme. It's definitely an effort to build a project like that but the payoff is worth it. We've already noticed huge savings in time and resources by utilizing theme's features and I'm certain you will too.

Happy coding!