@creativestyle/magesuite-frontend-builder

A modern build system for Magento 2 / MageSuite themes built on Webpack 5, TypeScript, and Gulp 5. Provides webpack bundling, SCSS compilation, asset copying, image optimisation, linting, BrowserSync dev proxy, and Magento cache management — all wired together in a single package consumed by child themes.

Features

• Webpack 5 with TypeScript compilation and persistent filesystem cache
• Hot CSS injection via BrowserSync — no page reloads for style changes
• Multi-level theme inheritance — file resolution walks the full theme.xml parent chain
• Modern tooling — ESLint flat config, Stylelint v17, Prettier, Husky v9, lint-staged
• Interactive command menu — yarn menu for arrow-key navigation of all available tasks
• Production optimisation — CSS minification, image compression, WOFF2-only fonts

Quick start

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

Individual gulp tasks can also be run directly. Use yarn gulp <task> — not bare gulp <task> (no global install) and not yarn <task> (these tasks are not listed in package.json scripts):

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

Directory structure

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 inheritance system

The builder supports multi-level theme inheritance. File resolution walks the full theme.xml parent chain at build time:

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

Resolution order for any given file:

1. Current theme src/
2. Parent theme src/
3. Base theme src/ (theme-creativeshop)
4. node_modules/

Webpack aliases and module resolution paths are populated automatically from this chain — no manual path configuration needed in child themes.

Parent theme setup

Each theme declares its parent in 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>

The builder reads this file to build the alias map and resolve entry points across all levels of the chain.

Theme integration

Themes consume the builder via gulpfile.mjs:

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

To override webpack config, add a webpack.config.js to your theme root — it will be deep-merged with the base config via webpack-merge.

Child theme 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"
    }
}

Child theme tsconfig.json

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

Child theme src/declarations.d.ts

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

TypeScript has no built-in understanding of SCSS imports or Magento's RequireJS modules, so without this file tsc (and the ESLint TypeScript parser) would error on:

• import '*.scss' — theme TS files often import SCSS; TypeScript treats unknown extensions as missing modules.
• import ... from 'mage/translate' etc. — Magento core ships no .d.ts files, so all mage/* imports are unresolved types.

The file suppresses both classes of errors globally without touching any theme source file.

Development workflow

Starting development

# Install dependencies
yarn install

# Start the development server
yarn serve

BrowserSync starts a reverse proxy in front of Magento. CSS changes are injected without a page reload; JS changes trigger a reload. SSL is handled automatically via mkcert — see LOCAL_SSL_CERT.md.

Production build

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

Linting

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

The pre-commit hook (Husky + lint-staged) runs ESLint and Stylelint automatically on staged files before every commit.

Interactive menu

yarn menu opens an arrow-key navigable launcher with per-item descriptions. No need to remember command names.

Adding to a theme

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

The binary is wired up automatically via the bin field in the builder's package.json.

Menu groups

TypeScript compilation pipeline

TypeScript is compiled by ts-loader inside Webpack with transpileOnly: true — strips types and emits JavaScript but skips type checking. This keeps build times fast.

Type checking is handled separately by tsc --noEmit, which runs alongside ESLint during 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

The pre-commit hook runs ESLint on staged files only — not tsc. Type errors do not block commits; they surface via yarn lint:js or CI.

resolutions — caniuse-lite

Add a resolutions field to the child theme's package.json:

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

caniuse-api (a transitive dependency of autoprefixer) declares caniuse-lite@^1.0.0 — a loose range that resolves to a stale version, triggering "browsers data is N months old" warnings on every build. The resolutions field collapses all nested caniuse-lite entries to a single up-to-date version in yarn.lock.

Run yarn install --force after adding the field to apply the resolution.

Package reference

Build orchestration

Webpack and JS bundling

CSS processing

Asset handling

Linting and formatting

Interactive menu

Git hooks

What changed in v5.0 vs v4.x

Adopted

Intentionally suppressed — and why

Troubleshooting

CSS not injecting via BrowserSync

• Verify you are accessing the BrowserSync URL (with port), not the Magento URL directly
• Check the proxy target in gulp/config/browserSync.js matches your local domain
• Ensure CSS files are being generated in the correct web/css/ directory

"Module not found" errors

• Check tsconfig.json paths — the parent theme path must match the actual relative location
• Verify the parent theme is present at vendor/creativestyle/<parent-theme>/
• Run yarn install to ensure all builder dependencies are installed

Stale webpack cache after branch switch

yarn gulp cleanWebpackCache

Run this after switching branches with major config differences or after changing webpack aliases — the persistent cache does not detect alias changes automatically.

[DEP0060] util._extend deprecation during yarn serve

Cause: BrowserSync depends on http-proxy (unmaintained since 2020) which uses the deprecated util._extend API. Surfaces on Node.js 22+.

Impact: None — yarn serve works correctly. Cosmetic noise only. Open upstream: BrowserSync issue #2091.

Further reading

• CHANGELOG.md — version history
• LOCAL_SSL_CERT.md — setting up local HTTPS for BrowserSync