Upgrade to frontend builder v2 for the Back Office

This document provides instructions for moving a project from the @spryker/oryx-for-zed npm package — builder v1 — to builder v2, which ships inside the Gui module.

For an overview of the builder, see Frontend builder for the Back Office v2.

Estimated migration time: 1h

Prerequisites

• Node.js 24.15.0 or later, npm 10 or later.
• spryker/gui 5.8.0 or later, together with the Back Office modules that allow it.

1) Update composer packages

Gui 5.8.0 ships the builder and the npm dependency set of the Back Office, and the Back Office modules released with it widen their spryker/gui constraint to allow it — see Back Office modules released with builder v2. Update Gui together with the modules that depend on it:

composer require spryker/gui:"^5.8.0" --no-update
composer update spryker/gui "spryker/*" "spryker-feature/*" --with-dependencies

Updating spryker/gui on its own fails or leaves the project in a broken state: the locked Back Office modules constrain Gui to an older minor, and composer does not update packages that are not listed in the update command.

2) Update Node.js and npm versions

1. In all deploy.*.yml files used by the frontend, set the 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.15.0",
    "npm": ">=10.0.0"
}

2. Declare the assets/Zed directory of the Gui module as an npm workspace, so that npm installs the builder’s dependencies:

"workspaces": [
    "vendor/spryker/gui/assets/Zed"
]

For what this does and how it changes the commands, see npm workspaces for the frontend builders.

3. Replace the zed:* scripts so they delegate to the spryker-zed-gui workspace, add the lint scripts, and add the configuration generation to postinstall:

"scripts": {
    "zed": "npm run build -w spryker-zed-gui --",
    "zed:watch": "npm run build:watch -w spryker-zed-gui --",
    "zed:production": "npm run build:production -w spryker-zed-gui --",
    "zed:lint": "npm run lint -w spryker-zed-gui --",
    "zed:stylelint": "npm run stylelint -w spryker-zed-gui --",
    "postinstall": "npm run update:config -w spryker-zed-gui"
}

If postinstall already runs the configuration generation of another builder, chain them:

"postinstall": "npm run update:config -w mp-zed-ui && npm run update:config -w spryker-zed-gui"

4. Remove the legacy builder:

"@spryker/oryx-for-zed": "~3.6.1"

5. Remove the Back Office build dependencies the project declared for the legacy builder. Gui declares the whole toolchain in vendor/spryker/gui/assets/Zed/package.json and has no peer dependencies, so a copy in the project pins a second version of the same package. Everything below is installed automatically through the spryker-zed-gui workspace and goes from your package.json:

• Toolchain: @babel/core, @babel/plugin-transform-class-properties, @babel/plugin-transform-runtime, @babel/preset-env, @babel/preset-typescript, @babel/runtime, @jest/globals, @types/jquery, @types/node, @typescript-eslint/eslint-plugin, @typescript-eslint/parser, autoprefixer, babel-loader, chokidar, commander, copy-webpack-plugin, css-loader, css-minimizer-webpack-plugin, eslint, fast-glob, imports-loader, jest, jest-environment-jsdom, mini-css-extract-plugin, postcss, postcss-loader, postcss-selector-parser, resolve-url-loader, sass-embedded, sass-loader, stylelint, stylelint-config-standard-scss, terser-webpack-plugin, ts-jest, typescript, webpack, webpack-merge.
• Runtime libraries of the Back Office: @fortawesome/fontawesome-free, @popperjs/core, @spryker/nestable, autonumeric, bootstrap, codemirror, datatables.net and its -bs5, -buttons, -buttons-bs5, -responsive, -responsive-bs5, -select, -select-bs5 packages, dompurify, flatpickr, highlight.js, jquery, jquery-migrate, jquery-ui, jstree, marked, pace, select2, summernote, sweetalert2.

Keep a package only if another builder in the project still declares it as a peer dependency. See What you can remove from your package.json.

4) Delete the project build script

If the project extended the legacy builder as described in Overriding Webpack, JS, SCSS for ZED on the project level, delete frontend/zed/build.js and any webpack configuration next to it. Each thing it did has a replacement:

The builder has no webpack configuration hook: the settings file overrides the source roots, the output directories, and the type checking switch, and everything else is fixed.

5) Generate the configuration

Run the generation:

npm run update:config -w spryker-zed-gui

It writes tsconfig.defaults.json, tsconfig.zed.json, and tsconfig.zed.lint.json into the builder directory, and creates the project root tsconfig.json as a solution file if the project has none. A root tsconfig.json that is a complete configuration of your own is left unchanged; its compilerOptions override the builder defaults. For the full ownership split, see Generated configuration.

postinstall runs the same command, so a plain npm install keeps the configuration current afterwards. The generated files are gitignored in the Gui module and regenerated on every install, so there is nothing to commit.

6) Fix Sass deprecations in project stylesheets

The legacy builder logged Sass deprecation warnings; builder v2 fails the build on a warning in a stylesheet the project owns. Run a build and fix what it reports:

• @import 'partial' of your own partial becomes @use 'partial'.
• @import '~package/file.css' becomes @use 'package/file.css' as *, or a require('package/file.css') in the entry point.
• A global color function becomes its sass:color equivalent: darken($color, 8%) becomes color.adjust($color, $lightness: -8%) after @use 'sass:color'.

Warnings from installed packages and from the Inspinia theme do not fail the build; they are printed as one summary line. See Stylesheets.

7) Install and build

npm install
npm run zed

Then verify the rest of the toolchain:

npm run zed:lint
npm run zed:stylelint

In a project, both cover src/Pyz/Zed only: the core modules arrive in vendor/ and are not the project’s to report on. zed:lint reports that type checking is off — it is off by default in a project, see TypeScript.

Finally, check the Back Office in the browser. Every entry point still produces js/<name>.js and css/<name>.css under the same names, so the templates need no change. The only new files are the hashed chunks under js/chunks/ and css/chunks/.

Back Office modules released with builder v2

The Back Office modules were released together with the builder — spryker/gui as a minor version, all the others as patch versions that allow Gui 5.8 in their constraints. The update command in step 1 picks them up automatically.

The patch releases change no behavior of their own: the entry point files keep their names, so the modules still build with the legacy builder as well. Some of them additionally carry lint fixes and the @use conversion of their stylesheets, which is what removes the Sass deprecation warnings from the core modules under builder v2.

Behavior changes

• Code loaded on demand is no longer in the shared bundle. The legacy builder merged every library loaded with import() into spryker-zed-gui-commons.js, so it was present on every page whether the page needed it or not. Builder v2 emits such code as separate chunks fetched on first use. Project code that relied on one of these libraries being available synchronously on every page has to import it explicitly.
• animate.css and metismenu are gone from the Gui runtime dependencies; nothing in the Back Office imported them. If your project does, declare them in your own package.json.
• Runtime libraries moved to newer versions: jQuery 3.7, jQuery Migrate 3.6, Select2 4.1, AutoNumeric 4.10, and marked 18. Select2 4.1 changes its generated markup — the clear button of a select with allowClear is a <button class="select2-selection__clear"> element — so end-to-end tests that select buttons inside a Select2 container may need narrower selectors.
• Sass deprecations in project stylesheets fail the build — see step 6.

Post-upgrade notes

• Live reload. npm run zed:watch now reloads the open Back Office page after a .js, .ts, .scss, or .twig change; a CSS-only change is applied without a reload. No extra setup is needed. Set SPRYKER_FRONTEND_RELOAD=0 to turn it off. A Twig change shows up after the reload only when ApplicationConstants::ENABLE_APPLICATION_DEBUG is on, which is the default in a Docker SDK development environment; otherwise run docker/sdk console twig:cache:warmer — see Live reload.
• TypeScript. Back Office modules can ship .entry.ts and .ts files. To type-check the project’s own TypeScript, set typecheck: true in frontend/backoffice.settings.mts.
• Lint scope. npm run zed:lint and npm run zed:stylelint report on src/Pyz/Zed only. Project-level lint configuration lives at the project root: eslint.config.backoffice.mjs and stylelint.config.backoffice.mjs. Without them, the configurations shipped in Gui are used.
• A core module added to or removed from the project changes the generated @zed/* aliases and include globs. postinstall regenerates them on the next npm install.