Set up an initial custom theme

Luma is a better looking theme than Blank, but it contains a lot of extra code and design specifics that may interfere with our new theme. That extra code which makes it look better will also get in the way of our new design. So, we know that we must just about always define “blank” as the parent theme to extend from.

But don’t completely disregard Luma. It’s a great example of how to create a custom theme extending from Blank, and since it’s in the core, you can be sure that it follows Magento’s best practices of custom theming. This means that if something is customized in Luma, you can check it out to determine how to do the same in your own custom theme.

The first thing we need to do is create directory at app/design/frontend/<Vendor>/<theme>. Our Vendor name will be our own name or company name, and the theme name will be what we want to name this theme. In this case since my company name is Macademy, I will name this first directory Macademy, with a capital first letter. The theme we’ll be creating in this course is named “Juno”. I thought it sounded fun, and it’s real easy to type. But rather than typing Juno with a capital letter, we’ll make sure this directory is all lowercase, so this will be juno.

Since this is the convention that Magento uses, it’s also a good convention for us to follow.

We know that three files basically make up the base of a theme: a registration.php file, a composer.json file, and a theme.xml file. Let’s create each of these.

The registration.php file registers your theme with Magento, so that it can be used by it and load all of the subsequent PHP and XML files. Without it, Magento won’t know that your theme exists.

registration.php

<?php declare(strict_types=1);

use Magento\\Framework\\Component\\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Macademy/juno',
    __DIR__
);

Next is the composer.json file. This file is actually optional, but it can be used to define dependencies for your theme, such as third-party libraries or other themes. I recommend to always create a composer.json file for your custom themes, if nothing else than to allow customers of your theme to track the version of your theme. This lets them know which version they have currently installed and which version is the most up to date.

composer.json

{
    "name": "juno/magento2-theme-juno",
    "description": "The Juno theme is built on top of the blank theme.",
    "require": {
        "php": "^7|^8",
        "magento/framework": ">=103",
        "magento/theme-frontend-blank": ">=100"
    },
    "type": "magento2-theme",
    "version": "1.0.0",
    "license": [
        "MIT"
    ],
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

And finally, the theme.xml file defines basic information about your theme, such as its name, parent theme, and the locations of the other files that make up the theme. This XML file makes your theme visible to the Magento configuration, and let’s it know which theme to use as the parent theme to extend from.

theme.xml

<?xml version="1.0"?>
<theme xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Juno</title>
    <parent>Magento/blank</parent>
</theme>

Once you have created these files, they will all be used together by Magento to register and manage your theme. These are absolute bare requirements for getting a theme set up. Now that our base theme files have been created, it’s time to get the theme activated.