Building a Hyvä Child Theme

A Hyvä child theme inherits all templates, layouts, and styles from the parent Hyvä Default Theme, allowing you to customize your store safely. Child themes are the recommended approach for Hyvä customization, ensuring upgrade compatibility and separating your code from vendor files.

This guide covers creating a child theme in app/design/frontend/, configuring Tailwind CSS to include parent theme sources, and generating the production stylesheet.

Creating a Child Theme

Create your new theme directory structure in app/design/frontend/Vendor/ThemeName/ by following the official Magento theme creation guide.

In your theme's theme.xml, set the parent to Hyva/default for the standard Hyvä theme, or Hyva/default-csp for the Content Security Policy compliant version.

Setting Up the Tailwind Build Directory

Child themes require a full copy of the parent theme's Tailwind build configuration, including package.json, Tailwind config files, and source CSS, to generate their stylesheet.

Step 1: Copy the Web Directory

Copy the entire web directory from the parent Hyvä Default Theme to your child theme:

mkdir -p app/design/frontend/Vendor/ThemeName/web
cp -r vendor/hyva-themes/magento2-default-theme/web/* app/design/frontend/Vendor/ThemeName/web/

Step 2: Configure the Parent Theme Path

Tailwind needs to scan the parent theme's templates to include their CSS classes in the production build. Configure this path in your child theme's web/tailwind/hyva.config.json.

Add a src entry to the tailwind.include array, pointing to the parent theme in the vendor directory:

{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme" }
        ]
    }
}

```js
module.exports = {
  ...
  // Examples for excluding patterns from purge
  content: [
    // this theme's phtml and layout XML files
    '../../**/*.phtml',
    '../../*/layout/*.xml',
    '../../*/page_layout/override/base/*.xml',
    // parent theme in Vendor (if this is a child-theme)
    //'../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
    //'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/layout/*.xml',
    //'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/page_layout/override/base/*.xml',
    // app/code phtml files (if need tailwind classes from app/code modules)
    //'../../../../../../../app/code/**/*.phtml',
  ]
}
...
```

If your theme is based on hyva-themes/magento2-default-theme-csp, adjust the path to include the -csp suffix:

{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

  module.exports = {
  ...
  // keep the original settings from tailwind.config.js
  // only add the path below to the purge > content settings
  ...
  purge: {
    content: [
      // this theme's phtml and layout XML files
      '../../**/*.phtml',
      '../../*/layout/*.xml',
      // parent theme in Vendor
      '../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
      ...
    ]
  }
}
...

Customizing Your Theme

Customize your Hyvä child theme using standard Magento extension mechanisms. Override .phtml templates by placing them in the same relative path within your child theme. Extend layout XML files using Magento's standard merging behavior.

Tailwind CSS utility classes from your custom templates are automatically included when you regenerate the CSS.

Generating the Production Stylesheet

After making changes, regenerate your child theme's styles.css to include new Tailwind classes. Run the Tailwind build command from your theme's web/tailwind directory:

npm run build

For more details on Tailwind CSS configuration and stylesheet generation, see:

• Working with Tailwind CSS
• Generating the styles.css file
• Tailwind CSS content configuration