@creativetyle/magesite-frontend-buildinger (英语)

Magento 2 / MageSuite主题的现代构建系统 网页包 5, (中文(简体) ), 类型脚本,以及 纸浆5. 提供webpack捆绑,SCSS编译,资产复制,图像优化,linting,浏览器Sync dev代理,和Magento缓存管理——都用被儿童主题所消耗的单个包连接在一起.

特征

• 网页包 5 包含 TypeScript 编译和持久文件系统缓存
• 热CSS注射 通过浏览器Sync – 没有页面重载样式变化
• 多层次主题继承 ——文件解析度走满 theme.xml 父链
• 现代工具 ——ESLint平面配置 Stylelint v17, Prettier, Husky v9, lint-staged (英语)
• 交互式命令菜单 —— 说 yarn menu 所有可用任务的箭头键导航
• 生产优化 —— CSS minification, 图像压缩, WOFF2- 只用字体

快开始

yarn install

yarn menu           # interactive command menu — recommended starting point
yarn build          # production build
yarn build:verbose  # production build with full asset size report
yarn serve          # development watch mode with BrowserSync
yarn lint           # ESLint + Stylelint
yarn lint:js        # ESLint only
yarn lint:css       # Stylelint only

个人gulp任务也可以直接运行. 使用 yarn gulp <task> - 不裸着 gulp <task> (没有全局安装)而不是 yarn <task> (这些任务未列在 package.json 脚本 :

yarn gulp cleanWebpackCache   # wipe webpack filesystem cache
yarn gulp eslint --fix        # lint and auto-fix JS/TS
yarn gulp stylelint --fix     # lint and auto-fix SCSS

目录结构

magesuite-frontend-builder/
├── registry.js                 # Entry point — registers all tasks and composes build/serve/watch
├── menu.js                     # Interactive CLI menu binary (magesuite-menu)
├── eslint.config.js            # ESLint flat config (JS + TS, Prettier integration)
├── package.json
│
├── config/                     # Theme-level config files re-exported by child themes
│   ├── lint-staged.js          # lint-staged config — runs ESLint + Stylelint on staged files
│   ├── prettier.js             # Prettier config
│   └── stylelint.js            # Stylelint config
│
└── gulp/
    ├── environment.js          # CLI flag parser — development / production / ci / watch / verbose
    ├── paths.js                # Resolved src/dist/pubStatic paths from composer.json
    ├── collectEntries.js       # Resolves webpack entry points across theme inheritance chain
    ├── collectParents.js       # Walks theme.xml <parent> chain → ordered list of parent paths
    ├── parentAliases.js        # Builds webpack alias map (e.g. Creativeshop → parent src/)
    ├── skipUnchangedPlugin.js  # Webpack plugin — skips emitting assets identical to dist
    ├── imageminStream.js       # Gulp stream that runs images through imagemin plugins
    ├── imageminSharpJpeg.js    # Imagemin plugin — JPEG compression with sharp's mozjpeg encoder
    ├── imageminSharpPng.js     # Imagemin plugin — PNG palette compression with sharp's libimagequant
    ├── srcExists.js            # Guards gulp.src() calls — prevents ENOENT when optional dirs are absent
    │
    ├── config/                 # Per-task configuration
    │   ├── browserSync.js      # BrowserSync proxy settings and all rewrite middleware
    │   ├── buildSprites.js     # SVG sprite generation settings
    │   ├── buildWebpack.js     # Full webpack configuration (entries, loaders, plugins, cache)
    │   ├── clean.js            # Paths deleted by the clean task
    │   ├── cleanCache.js       # Magento cache types + connection config (ssh/local/docker)
    │   ├── collectViewXml.js   # Source paths for view.xml collection
    │   ├── copyDocs.js         # Glob patterns for documentation assets
    │   ├── copyHtml.js         # Glob patterns for HTML templates
    │   ├── copyImages.js       # Glob patterns + imagemin plugin options
    │   ├── copyScripts.js      # Glob patterns for plain JS vendor scripts
    │   └── copyUnchanged.js    # Glob patterns for all other static assets
    │
    └── tasks/                  # Individual gulp task implementations
        ├── browserSync.js
        ├── buildWebpack.js
        ├── clean.js
        ├── cleanCache.js
        ├── cleanWebpackCache.js
        ├── collectViewXml.js
        ├── copyDocs.js
        ├── copyHtml.js
        ├── copyImages.js
        ├── copyScripts.js
        ├── copyUnchanged.js
        ├── eslint.js
        ├── generateCerts.js
        └── stylelint.js

主题继承制度

构建者支持多层次的主题继承. 文件解析度走满 theme.xml 构建时间的父链 :

theme-creativeshop  (base)
└── theme-child
    └── theme-grandchild

任一文件的解析命令 :

1. 当前主题 src/
2. 父主题 src/
3. 基础主题 src/ (主题编剧)
4. node_modules/

Webpack别名和模块解析路径从这个链中自动被接通——儿童主题不需要手动路径配置.

父主题设置

每个主题都声明其母于 src/theme.xml数字 :

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Child Theme</title>
    <parent>Creativestyle/theme-creativeshop</parent>
</theme>

构建者读取了这个文件来构建异名映射并解决跨链条所有级别的出入口.

主题整合

主题通过 gulpfile.mjs数字 :

import gulp from 'gulp';
import registry from '@creativestyle/magesuite-frontend-builder';
gulp.registry(registry);

要覆盖 Webpack 配置,请添加一个 webpack.config.js 到您的主题根 —— 它将随着底部配置通过 webpack-merge。 。 。 .

儿童主题 package.json

{
    "scripts": {
        "menu":         "magesuite-menu",
        "build":        "gulp build --env production",
        "build:verbose":"gulp build --env production --verbose",
        "serve":        "gulp serve",
        "start":        "gulp serve",
        "lint:js":      "gulp eslint",
        "lint:css":     "gulp stylelint",
        "lint":         "gulp eslint && gulp stylelint",
        "prepare":      "husky"
    },
    "resolutions": {
        "caniuse-lite": "^1.0.30001781"
    }
}

儿童主题 tsconfig.json

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "commonjs",
        "moduleResolution": "node",
        "noEmit": true,
        "skipLibCheck": true,
        "paths": {
            "*": ["./src/*", "./node_modules/*", "../theme-creativeshop/src/*"]
        }
    }
}

儿童主题 src/declarations.d.ts

declare module '*.scss';
declare module 'mage/*';

TypeScript 对 SCSS 导入或 Magento 的要求JS 模块没有内置的理解, 因此没有此文件 tsc (和ESLint TypeScript 解析器)会错误于:

• import '*.scss' ——主题TS文件常导入SCSS;TypeScript将未知扩展作为缺失模块.
• import ... from 'mage/translate' - 马根托核心船 .d.ts 文档,所以 mage/* 进口是未解决的类型.

文件在不触及任何主题源文件的情况下,将两种错误压制在全球.

发展工作流程

开始发展

# Install dependencies
yarn install

# Start the development server
yarn serve

浏览器Sync在Magento前启动一个倒置代理. CSS更改是在不重新加载页面的情况下被注入;JS更改会触发重新加载. SSL 是通过 mkcert 自动处理的 — 见 现场 SSL CERT.md。 。 。 .

生产建设

yarn build          # concise summary output
yarn build:verbose  # full asset list with sizes and all warnings

线性

yarn lint           # ESLint + Stylelint
yarn lint:js        # ESLint + tsc --noEmit
yarn lint:css       # Stylelint

# Auto-fix formatting and fixable violations
yarn gulp eslint --fix
yarn gulp stylelint --fix

承诺前的钩子(Husky + lint-staged)在每次承诺前都会自动地在已上演的文件上运行ESLint和Stylelint.

交互式菜单

yarn menu 打开带有每个项目描述的箭键可导航发射器。 不需要记住命令名称.

添加到主题中

"scripts": {
    "menu": "magesuite-menu"
}

二进制自动通过 bin 字段中的字段 package.json。 。 。 .

菜单组

TypeScript 编译管道

类型脚本由 ts-loader 在 Web 软件包内 transpileOnly: true ——字条类型并释放出JavaScript但跳过类型检查. 这让时间变得很快.

类型检查由 tsc --noEmit,它与 ESLint 期间同时运行 yarn lint:js数字 :

yarn build    → Webpack + ts-loader (transpileOnly: true) → fast, no type errors surfaced
yarn lint:js  → tsc --noEmit + ESLint                    → type errors and lint violations reported

承诺前的钩子运行 仅将 ESLint 放在已播放的文件 -没有 tsc。类型错误不阻断输入;它们通过 yarn lint:js (原始内容存档于2018-03-26). 或CI.

resolutions - 罐头油

添加一个 resolutions 字段到子主题 package.json数字 :

"resolutions": {
    "caniuse-lite": "^1.0.30001781"
}

caniuse-api (自动前置器的过渡依赖) caniuse-lite@^1.0.0 ——一个松散的范围,它决定了一个僵硬的版本,在每个建筑上触发"浏览器数据是N个月的"警告. 这个 resolutions 字段崩溃全部嵌入 caniuse-lite 条目为: yarn.lock。 。 。 .

运行 yarn install --force 在添加字段以应用决议后.

软件包参考

构建管弦乐

网络包装和联署材料捆绑

CSS 处理

资产处理

定型和格式化

交互式菜单

巨钩

V 5.0 vs 4.x中的变化

通过

故意压制——为什么

解决问题

CSS 不通过浏览器注入Sync

• 校验您正在访问浏览器Sync URL(带有端口),而不是直接访问 Magento URL
• 检查代理目标 gulp/config/browserSync.js 匹配您的本地域
• 确保 CSS 文件生成正确无误 web/css/ 目录

“ 未找到模块” 错误

• 检查 tsconfig.json paths ——母主题路径必须与实际相对位置相匹配
• 校验父主题在 vendor/creativestyle/<parent-theme>/
• 运行 yarn install 以确保安装所有构建者的依赖性

分支切换后 Stale 网络包缓存

yarn gulp cleanWebpackCache

在切换有主要配置差异的分支后或更改了webpack别名后运行此功能——持久的缓存不会自动检测出别名的更改.

[DEP0060] util._extend 折旧期间 yarn serve

原因 : 浏览器同步取决于 http-proxy (自2020年以来未保留)使用已贬值的 util._extend API. 地平面在节点.js 22+.

影响 : 无 - yarn serve 工作没错 只有化妆的噪音。 上游打开 : 浏览器同步 第2091期。 。 。 .

进一步阅读

• 变动情况 ——版本历史
• 现场 SSL CERT.md – 为浏览器Sync 设置本地 HTTPS