Hyvä子主题创建工具 - 快速生成Magento 2 Hyvä主题目录与配置文件

hyva-child-theme by hyva-themes/hyva-ai-tools

166 周安装量

59 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/hyva-themes/hyva-ai-tools --skill hyva-child-theme

开发自动化电商

🇨🇳中文介绍

Hyvä Child Theme Creator

此技能用于创建一个完整的 Hyvä 子主题，包含正确的目录结构、配置文件以及 Tailwind CSS 构建设置。

命令执行： 对于需要在开发环境内运行的命令（例如 bin/magento），请使用 hyva-exec-shell-cmd 技能来检测环境并确定合适的命令包装器。

工作流程

步骤 1：收集主题信息

提示用户提供以下信息：

供应商名称 : 供应商/公司命名空间（例如 "Acme", "MyCompany"）

必须使用 PascalCase 格式
用于 composer 包名和目录结构
如果 app/design/frontend 或 app/code/ 中已存在供应商名称文件夹，则以小写形式提供这些作为建议

主题名称 : 主题的名称（例如 "customTheme", "StoreTheme"）

必须使用 PascalCase 或 camelCase 格式
用于主题注册和目录名
不能作为子目录存在于 app/design/frontend 中

步骤 2：检测父主题

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：创建主题目录结构

在 app/design/frontend/<Vendor>/<themeName>/ 创建主题目录，包含：

app/design/frontend/<Vendor>/<themeName>/
├── registration.php
├── theme.xml
├── composer.json
└── web/
    └── tailwind/
        └── (从父主题复制)

步骤 4：创建配置文件

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register( ComponentRegistrar::THEME, 'frontend/<Vendor>/<themeName>', __DIR__);

<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Example Store Theme</title>
    <parent>Hyva/default-csp</parent>
</theme>

标题格式化： 将 PascalCase 主题名称拆分为单独的单词（例如 StoreTheme → Store Theme）。标题应读作 <Vendor> <Theme Name Words>（例如 Example/StoreTheme → Example Store Theme）。

调整 <parent> 以匹配选定的父主题：

Hyvä 默认主题使用 Hyva/default-csp 或 Hyva/default
子主题父级使用 {ParentVendor}/{ParentThemeName}（例如 Example/baseTheme）

{
    "name": "<vendor-lowercase>/<package-name>",
    "description": "Example Store Theme based on Hyvä",
    "type": "magento2-theme",
    "license": "proprietary",
    "require": {
        "hyva-themes/magento2-default-theme-csp": "*"
    },
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

将 <ThemeName> 转换为 kebab-case（例如 StoreTheme → store-theme）
仅当主题名称不以 "theme" 结尾时，才附加 -theme 后缀
示例：
- StoreTheme → store-theme（已以 "theme" 结尾，不添加后缀）
- CustomStore → custom-store-theme（添加后缀）
- myTheme → my-theme（已以 "theme" 结尾，不添加后缀）

调整 require 依赖项以匹配父主题：

对于 Hyvä 默认主题：hyva-themes/magento2-default-theme-csp 或 hyva-themes/magento2-default-theme
对于子主题父级：使用父主题的 composer 包名（来自其 composer.json），如果父主题不是 composer 包，则省略

步骤 5：复制并配置 Tailwind

创建 web 目录并从父主题复制 tailwind 文件夹，排除 node_modules（复制的 node_modules 包含损坏的符号链接，必须重新安装）：

mkdir -p app/design/frontend/<Vendor>/<ThemeName>/web
rsync -a --exclude='node_modules' <parent_theme_path>/web/tailwind app/design/frontend/<Vendor>/<ThemeName>/web/

其中 <parent_theme_path> 是：

Hyvä default-csp 对应 vendor/hyva-themes/magento2-default-theme-csp
Hyvä default 对应 vendor/hyva-themes/magento2-default-theme
子主题父级对应 app/design/frontend/{ParentVendor}/{ParentTheme}

更新 web/tailwind/hyva.config.json，将父主题路径包含在 Tailwind 内容扫描中。

对于 Hyvä 默认主题父级：

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

对于子主题父级： 同时包含直接父级和根 Hyvä 主题，以确保扫描所有模板类：

{
    "tailwind": {
        "include": [
            { "src": "app/design/frontend/{ParentVendor}/{ParentTheme}" },
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

如果子主题父级的 hyva.config.json 中已有额外的包含项，请复制这些项以维护完整的继承链。

步骤 6：安装依赖项并构建 CSS

使用 hyva-compile-tailwind-css 技能为新创建的主题（位于 app/design/frontend/<Vendor>/<ThemeName>/）安装依赖项并构建 CSS。

步骤 7：启用主题

告知用户可以通过以下方式启用主题：

Magento 后台：内容 > 设计 > 配置
或通过 CLI：bin/magento config:set design/theme/theme_id <theme_id>

运行 setup upgrade 以注册主题：

bin/magento setup:upgrade
bin/magento cache:flush

未找到 Hyvä 主题（步骤 2）

原因：项目中未安装 Hyvä 主题包。解决方案：通过 Composer 安装 Hyvä 主题：composer require hyva-themes/magento2-default-theme 或 hyva-themes/magento2-default-theme-csp。

父主题路径不存在（步骤 5）

原因：选定的父主题目录缺失或路径不正确。解决方案：在运行 rsync 之前验证父主题是否存在。使用 composer install 检查 Composer 包是否正确安装。

父主题中缺少 Tailwind 文件夹（步骤 5）

原因：父主题没有 web/tailwind 目录（可能出现在非常旧或自定义的主题中）。解决方案：回退到从 vendor/hyva-themes/magento2-default-theme-csp/web/tailwind 复制 tailwind 文件夹。

npm install 失败（步骤 6）

原因：Node 版本不匹配、网络问题或 package-lock.json 损坏。解决方案：

检查 Node 版本（需要 Node 16+）：node --version
删除 node_modules 和 package-lock.json，然后重试 npm install

npm build 失败（步骤 6）

原因：hyva.config.json 中的路径无效或缺少清除目标。解决方案：

验证 hyva.config.json 中的所有路径是否存在于项目中
检查配置文件中的 JSON 语法错误
确保父主题路径正确

成功创建后，提供摘要：

主题位置：app/design/frontend/<Vendor>/<ThemeName>/
父主题：选定的父主题（例如 Hyva/default-csp、Hyva/default 或 {Vendor}/{ThemeName}）
自定义的后续步骤：
- 通过创建匹配的路径来覆盖模板
- 在 web/tailwind/tailwind-source.css 中自定义 Tailwind
- 开发时运行 npm run watch
- 部署前运行 npm run build

🇺🇸English

Hyvä Child Theme Creator

This skill creates a complete Hyvä child theme with the proper directory structure, configuration files, and Tailwind CSS build setup.

Command execution: For commands that need to run inside the development environment (e.g., bin/magento), use the hyva-exec-shell-cmd skill to detect the environment and determine the appropriate command wrapper.

Workflow

Step 1: Gather Theme Information

Prompt the user to provide the following information:

Vendor Name : The vendor/company namespace (e.g., "Acme", "MyCompany")

Must be PascalCase
Used in composer package name and directory structure
If there are existing Vendor name folders in app/design/frontend or app/code/ offer those in lower case as suggestions

Theme Name : The name of the theme (e.g., "customTheme", "StoreTheme")

Must be PascalCase or camelCase
Used in theme registration and directory name
Must not be present as a subdirectory in app/design/frontend

Step 2: Detect Parent Theme

If the user has specified a parent theme, use that. The parent can be:

A Hyvä default theme: Hyva/default-csp or Hyva/default
An existing Hyvä child theme: {Vendor}/{ThemeName} from app/design/frontend/

If the user has NOT specified a parent theme, discover available options by invoking the hyva-theme-list skill to find all Hyvä themes in the project.

Present the user with options to select a parent theme:

Hyvä default themes : Hyva/default-csp (if installed) or Hyva/default
Existing Hyvä child themes : List themes returned by the skill as {Vendor}/{ThemeName}

Parent theme paths for later steps:

Hyvä default themes: vendor/hyva-themes/magento2-default-theme-csp or vendor/hyva-themes/magento2-default-theme
Child themes: app/design/frontend/{Vendor}/{ThemeName}

Step 3: Create Theme Directory Structure

Create the theme directory at app/design/frontend/<Vendor>/<themeName>/ with:

app/design/frontend/<Vendor>/<themeName>/
├── registration.php
├── theme.xml
├── composer.json
└── web/
    └── tailwind/
        └── (copied from parent theme)

Step 4: Create Configuration Files

registration.php

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register( ComponentRegistrar::THEME, 'frontend/<Vendor>/<themeName>', __DIR__);

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>Example Store Theme</title>
    <parent>Hyva/default-csp</parent>
</theme>

Title formatting: Split PascalCase theme names into separate words (e.g., StoreTheme → Store Theme). The title should read as <Vendor> <Theme Name Words> (e.g., Example/StoreTheme → Example Store Theme).

Adjust <parent> to match the selected parent theme:

Hyva/default-csp or Hyva/default for Hyvä default themes
{ParentVendor}/{ParentThemeName} for child theme parents (e.g., Example/baseTheme)

composer.json

{
    "name": "<vendor-lowercase>/<package-name>",
    "description": "Example Store Theme based on Hyvä",
    "type": "magento2-theme",
    "license": "proprietary",
    "require": {
        "hyva-themes/magento2-default-theme-csp": "*"
    },
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

Package name rules:

Convert <ThemeName> to kebab-case (e.g., StoreTheme → store-theme)
Append -theme suffix only if the theme name doesn't already end with "theme"
Examples:
- StoreTheme → store-theme (already ends with "theme", no suffix added)
- CustomStore → custom-store-theme (suffix added)
- myTheme → my-theme (already ends with "theme", no suffix added)

Adjust the require dependency to match the parent theme:

For Hyvä default themes: hyva-themes/magento2-default-theme-csp or hyva-themes/magento2-default-theme
For child theme parents: Use the parent's composer package name (from its composer.json), or omit if the parent theme is not a composer package

Step 5: Copy and Configure Tailwind

Create the web directory and copy the tailwind folder from the parent theme, excluding node_modules (copied node_modules contain broken symlinks and must be installed fresh):

mkdir -p app/design/frontend/<Vendor>/<ThemeName>/web
rsync -a --exclude='node_modules' <parent_theme_path>/web/tailwind app/design/frontend/<Vendor>/<ThemeName>/web/

Where <parent_theme_path> is:

vendor/hyva-themes/magento2-default-theme-csp for Hyvä default-csp
vendor/hyva-themes/magento2-default-theme for Hyvä default
app/design/frontend/{ParentVendor}/{ParentTheme} for child theme parents

Update web/tailwind/hyva.config.json to include the parent theme path(s) in Tailwind content scanning.

For Hyvä default theme parent:

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

For child theme parent: Include both the immediate parent AND the root Hyvä theme to ensure all template classes are scanned:

{
    "tailwind": {
        "include": [
            { "src": "app/design/frontend/{ParentVendor}/{ParentTheme}" },
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

If the child theme parent already has additional includes in its hyva.config.json, copy those to maintain the full inheritance chain.

Step 6: Install Dependencies and Build CSS

Use the hyva-compile-tailwind-css skill to install dependencies and build CSS for the newly created theme at app/design/frontend/<Vendor>/<ThemeName>/.

Step 7: Enable the Theme

Inform the user they can enable the theme via:

Magento Admin: Content > Design > Configuration
Or via CLI: bin/magento config:set design/theme/theme_id <theme_id>

Run setup upgrade to register the theme:

bin/magento setup:upgrade
bin/magento cache:flush

Troubleshooting

No Hyvä themes found (Step 2)

Cause : Hyvä theme packages not installed in the project. Solution : Install Hyvä themes via Composer: composer require hyva-themes/magento2-default-theme or hyva-themes/magento2-default-theme-csp.

Parent theme path doesn't exist (Step 5)

Cause : The selected parent theme directory is missing or path is incorrect. Solution : Verify the parent theme exists before running rsync. Check that Composer packages are properly installed with composer install.

Tailwind folder missing in parent (Step 5)

Cause : The parent theme doesn't have a web/tailwind directory (possible with very old or custom themes). Solution : Fall back to copying the tailwind folder from vendor/hyva-themes/magento2-default-theme-csp/web/tailwind instead.

npm install fails (Step 6)

Cause : Node version mismatch, network issues, or corrupted package-lock.json. Solution :

Check Node version (requires Node 16+): node --version
Delete node_modules and package-lock.json, then retry npm install

npm build fails (Step 6)

Cause : Invalid paths in hyva.config.json or missing purge targets. Solution :

Verify all paths in hyva.config.json exist in the project
Check for JSON syntax errors in the config file
Ensure parent theme paths are correct

Output

After successful creation, provide a summary:

Theme location: app/design/frontend/<Vendor>/<ThemeName>/
Parent theme: The selected parent (e.g., Hyva/default-csp, Hyva/default, or {Vendor}/{ThemeName})
Next steps for customization:
- Override templates by creating matching paths
- Customize Tailwind in web/tailwind/tailwind-source.css
- Run npm run watch for development
- Run npm run build before deployment

Weekly Installs

166

Repository

hyva-themes/hyv…ai-tools

GitHub Stars

First Seen

Jan 27, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

github-copilot164

opencode160

codex160

gemini-cli156

amp155

kimi-cli155

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

152,900 周安装

Hyvä子主题创建工具 - 快速生成Magento 2 Hyvä主题目录与配置文件

🇨🇳中文介绍

Hyvä Child Theme Creator

工作流程

步骤 1：收集主题信息

步骤 2：检测父主题

相关 Skills

步骤 3：创建主题目录结构

步骤 4：创建配置文件

registration.php

theme.xml

composer.json

步骤 5：复制并配置 Tailwind

步骤 6：安装依赖项并构建 CSS

步骤 7：启用主题

故障排除

未找到 Hyvä 主题（步骤 2）

父主题路径不存在（步骤 5）

父主题中缺少 Tailwind 文件夹（步骤 5）

npm install 失败（步骤 6）

npm build 失败（步骤 6）

输出

🇺🇸English

Hyvä Child Theme Creator

Workflow

Step 1: Gather Theme Information

Step 2: Detect Parent Theme

Step 3: Create Theme Directory Structure

Step 4: Create Configuration Files

registration.php

theme.xml

composer.json

Step 5: Copy and Configure Tailwind

Step 6: Install Dependencies and Build CSS

Step 7: Enable the Theme

Troubleshooting

No Hyvä themes found (Step 2)

Parent theme path doesn't exist (Step 5)

Tailwind folder missing in parent (Step 5)

npm install fails (Step 6)

npm build fails (Step 6)

Output

最新 Skills