Upgrade to frontend builder v2 for Yves

This document provides instructions for upgrading from the legacy Yves frontend builder, located in the project’s frontend/ directory, to frontend builder v2, which ships inside the ShopUi module.

For an overview of the new builder and its features, see Frontend builder for Yves v2.

Estimated migration time: 1h

Prerequisites

Frontend builder v2 is executed by Node.js directly as TypeScript, so it requires:

• Node.js 24 or later
• npm 10 or later
• spryker-shop/shop-ui version 2.0.0 or later

1) Update composer packages

ShopUi 2.0.0 is a new major version, and most Yves modules constrain ShopUi to ^1.x, so they must be updated together with it. Each of them has a release that allows ShopUi 2—see Storefront modules released with builder v2.

1. Several feature packages constrain ShopUi and moved to semantic versioning. If your project requires them, update their constraints in composer.json:

"spryker-feature/ai-commerce": "^0.7.8",
"spryker-feature/buy-box": "^1.4.0",
"spryker-feature/purchasing-control": "^1.2.0",
"spryker-feature/self-service-portal": "^20.12.0",

2. Require ShopUi 2 and update it together with all modules that depend on it:

composer require spryker-shop/shop-ui:"^2.0.0" --no-update
composer update spryker-shop/shop-ui "spryker-shop/*" "spryker-feature/*" --with-dependencies

Running composer require spryker-shop/shop-ui:"^2.0.0" on its own fails: the locked module versions constrain ShopUi to ^1.x, and composer doesn’t update packages that aren’t listed in the update command. The wildcard arguments put every Spryker storefront and feature package into the update set, so composer can pick the releases that allow ShopUi 2.

Packages that moved to semantic versioning are reported as downgrades—for example, spryker-feature/purchasing-control (202606.0 => 1.2.0). This is expected: the semver releases continue the date-based release lines.

2) Update Node.js and npm versions

1. In all deploy.*.yml files used by the frontend, set the Node.js and npm versions:

image:
    ...
    node:
        version: 24
        npm: 10

2. If the project has an .nvmrc file, update it:

24

3) Update package.json

1. Update the engines:

"engines": {
    "node": ">=24.14.0",
    "npm": ">=10.0.0"
}

2. Replace the yves:* scripts so they point at the builder inside the ShopUi module:

"scripts": {
    "yves": "node ./vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/FrontendBuilder/build.mts development",
    "yves:watch": "node ./vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/FrontendBuilder/build.mts development-watch",
    "yves:production": "node ./vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/FrontendBuilder/build.mts production",
    "yves:stylelint": "node ./vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/FrontendBuilder/libs/lint/stylelint.mts"
}

3. Remove the scripts that no longer exist:

"yves:help": "node ./frontend/libs/command-line-parser --help",
"yves:stylelint:fix": "node ./frontend/libs/stylelint.mjs --fix",
"yves:lint:fix": "..."

The parameter overview previously provided by yves:help is now available via npm run yves -- --help.

4. Update the dependencies:

• Replace sass with sass-embedded:

"sass-embedded": "~1.97.0"

• Add chokidar (used by the watch mode’s Twig watcher):

"chokidar": "~4.0.3"

• Update the versions:

"compression-webpack-plugin": "~12.0.0",
"postcss": "~8.5.18"

• Remove the dependencies that the new builder doesn’t need:

"sass": "x.x.x",
"sass-resources-loader": "x.x.x",
"terser-webpack-plugin": "x.x.x"

Builder v2 uses only babel-loader, css-loader, postcss-loader, and sass-loader. The shared Sass context (settings, helpers, and cross-component mixins) is injected by the builder itself, so sass-resources-loader has no consumer left. Check for project-owned webpack configurations that still reference it before removing it.

4) Remove the legacy builder from the frontend/ directory

Delete the legacy builder code:

rm -rf frontend/build.js frontend/configs frontend/libs frontend/settings.js

Keep the following directories—they are project content, not builder code:

• frontend/assets/—project asset sources (images, fonts, icons)
• frontend/static/—static public files
• frontend/merchant-portal/—Merchant Portal build tooling (unrelated to the Yves builder)

5) Migrate custom builder settings

If your project never modified frontend/settings.js or frontend/configs/*, skip this step—the new builder works with zero configuration.

If the project registered custom namespaces or paths in frontend/settings.js, recreate them in the new override file frontend/yves.settings.mts:

// frontend/yves.settings.mts
import { defineConfig } from '../vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/FrontendBuilder/settings.mts';

export default defineConfig({
    paths: {
        sources: {
            newNamespace: './PATH_TO_YOUR_FOLDER',
        },
    },
});

Unlike v1, a single sources entry is enough—there are no separate dirs arrays to keep in sync. For the full list of supported overrides (paths.sources, paths.iconSprite, buildHooks), see Frontend builder for Yves v2.

6) Verify tsconfig.yves.json

The builder reads component path aliases from tsconfig.yves.json and requires the ShopUi alias to locate the core shared stylesheet. Make sure it’s present:

"paths": {
    "ShopUi/*": ["./vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/Theme/default/*"]
}

7) Install and build

1. Update package-lock.json and install dependencies:

docker/sdk cli npm install

2. Build the Yves frontend:

docker/sdk cli npm run yves

3. Verify the build:

• The build output starts with a Source layout: project (modules in vendor/) line.
• Assets are generated into public/Yves/assets/<namespace>/<theme>/ as before.
• The storefront renders with the expected styles.

Minimum changes to legacy project styles

Migrating the project styles to the Sass module system is not part of this upgrade. Project component files keep working in the legacy form—the builder injects the shared context (settings, helpers, and cross-component mixins) into every component file at compile time, so they need no @use rules of their own. Files that emit CSS at the top level compile with a legacy style rescue warning and stay in the bundles.

One legacy pattern fails to compile and must be adjusted: a shared helper mixin that reads a variable defined in the consuming component file.

// styles/helpers/_product-shared.scss
@mixin product-shared() {
    width: rem($image-size);
}

// components/molecules/my-product/my-product.scss
$image-size: 76;

@include product-shared();

The v1 builder prepended all styles into one global scope, so the mixin picked such a variable up dynamically at include time. Builder v2 loads the shared stylesheet as a Sass module, and a module mixin resolves variables lexically—in the stylesheet that defines the mixin—so the build fails with Undefined variable pointing at the mixin body.

Pass the value as a mixin parameter with a default instead:

// styles/helpers/_product-shared.scss
@mixin product-shared($image-size: 76) {
    width: rem($image-size);
}

// components/molecules/my-product/my-product.scss
@include product-shared();

Alternatively, move the variable declaration into the shared closure (for example, a styles/settings/ partial), where the mixin body can see it.

Optional: remove the Sass @import deprecation warnings

Most of the remaining deprecation warnings come from @import rules in the project styles/ layer. The biggest source is the project shared.scss wrapper: it is loaded into every compiled component, so each of its @import lines warns once per compilation. To remove the warnings, we recommend migrating the project styles/ layer from @import to the Sass module system—@use and @forward, supported since Dart Sass 1.23.0 (the sass-embedded version required by the builder includes it). Component files stay untouched: the builder injects the shared context into them, so only the styles/ layer migrates.

The format—the wrapper forwards the core shared stylesheet and the project partials:

// src/Pyz/Yves/ShopUi/Theme/default/styles/shared.scss
@use 'settings/color' as setting-color;

@forward '~ShopUi/styles/shared' with (
    $setting-color-main: setting-color.$setting-color-main,
    $setting-color-alt: setting-color.$setting-color-alt
);

@forward 'settings/color' hide $setting-color-main, $setting-color-alt;
@forward 'helpers/my-helper';

// src/Pyz/Yves/ShopUi/Theme/default/styles/helpers/_my-helper.scss
@use '../settings/color' as *;

@mixin helper-my-helper {
    color: $setting-color-main;
}

Two rules make the migration safe:

• Project overrides of core settings move into the with (...) configuration of the core forward, and the same names are hidden from the project partial’s forward. Forwarding two modules that define the same member is an error, and hiding the core member instead of configuring it would silently disconnect the project value from the core helpers that read it—the core !default settings exist exactly for this configuration.
• Every partial declares its own @use dependencies. In a module, a mixin resolves variables and helper mixins lexically—in the stylesheet that defines it—so a partial that references settings or other helpers must load them itself.

Storefront modules released with builder v2

The storefront modules were released together with the builder—spryker-shop/shop-ui as a major version, all the others as minor versions that allow ShopUi 2 in their constraints. The update command in step 1 picks them up automatically.

Modules that ship component styles received updated styles: base declarations are emitted before nested rules (the Sass mixed-decls fix), component styles follow the new entry-point contract, and component mixins expose base hooks. Updating them:

• removes the Sass mixed-decls deprecation warnings coming from the modules’ styles;
• removes the legacy style rescue warnings for components written against the old builder contract;
• makes base hooks available in the modules’ components.

The remaining modules only widen their ShopUi constraint.

Post-upgrade notes

• Sass deprecation warnings are no longer silenced. The v1 builder suppressed warnings from dependencies; builder v2 shows them and points at the real file. Fix them in your project code instead of suppressing—they become hard errors in future Sass versions. See the base hook mechanism in Extending components for the recommended way to extend core component base styles without triggering the mixed-decls deprecation.
• Legacy style rescue. Component SCSS files that emit CSS at the top level without being imported from a component entry point are still compiled, with a warning naming the file. Migrate such components by importing their styles from the component’s index.ts.
• Live reload. npm run yves:watch now includes live reload: CSS changes are applied without a page reload, and JavaScript and Twig changes trigger a full reload that preserves scroll position and form state. No extra setup is needed.

Example migration

For a complete, real-world application of this guide, see the B2B Demo Marketplace migration pull request: CC-37183 Move YVES builder into ShopUi. It covers every step of this document—the composer update, package.json and Node.js changes, the legacy builder removal, and the minimum project style adjustments.