Oryx for Zed

Edit on GitHub

oryx-for-zed is a tool that performs a full build for Spryker Zed UI applications. It also provides access to Zed settings and Zed Webpack configuration, so you can extend and change the whole building process.

Oryx framework

Oryx and oryx-for-zed should not be confused with the Oryx frontend framework that is used to create composable frontend applications.

Requirements

  • Node.js: minimum version is 18.
  • npm: minimum version is 9.
Note

oryx-for-zed starting from 2.13.0 version requires spryker/chart module version 1.4.0 or higher.

Setup

You need to add oryx-for-zed to your package.json. Open the terminal, go to your project root folder, and type:

npm install @spryker/oryx-for-zed --save-dev

Usage

Once installed, you can do the following actions:

  • Call the builder directly from your scripts (simple builder).
  • Extend or change the settings and Webpack configuration for your custom Zed build.

Simple builder

To run oryx-for-zed, follow the steps:

  1. Add the following script to your package.json:
{
  "scripts": {
    "build-zed": "node ./node_modules/@spryker/oryx-for-zed/build"
  }
}
  1. Open the terminal and type:
npm run build-zed

Extend or change the settings

Settings are extended and changed by using the oryx-for-zed API.

The following example shows how to create a custom build:

  1. In your project containing your custom settings and the logic needed to get the Webpack configuration, create a build.js file and run the builder:
const oryxForZed = require("@spryker/oryx-for-zed");
const { mergeWithCustomize, customizeObject } = require("webpack-merge");

const mergeWithStrategy = mergeWithCustomize({
  customizeObject: customizeObject({
    plugins: "prepend",
  }),
});

const myCustomZedSettings = mergeWithStrategy(oryxForZed.settings, {
  // your own settings
});

oryxForZed
  .getConfiguration(myCustomZedSettings)
  .then((configuration) =>
    oryxForZed.build(configuration, oryxForZed.copyAssets)
  )
  .catch((error) =>
    console.error("An error occurred while creating configuration", error)
  );
  1. Add a script into your package.json pointing to build.js:
{
  "scripts": {
    "build-zed": "node ./path/to/build"
  }
}

You will now be able to…

Extend and change the Webpack configuration

webpack is customized by using the oryx-for-zed API.

The following example shows how to create a custom build:

  1. In your project containing your Webpack custom configuration, create a webpack.config.js file:
const oryxForZed = require("@spryker/oryx-for-zed");
const { mergeWithCustomize, customizeObject } = require("webpack-merge");

const mergeWithStrategy = mergeWithCustomize({
  customizeObject: customizeObject({
    plugins: "prepend",
  }),
});

async function myCustomZedConfiguration() {
  const oryxConfiguration = await oryxForZed.getConfiguration(
    oryxForZed.settings
  );

  return mergeWithStrategy(oryxConfiguration, {
    // your own configuration
  });
}
  1. In your project containing your Webpack configuration and the logic needed to run the builder, create a build.js file:
const oryxForZed = require("@spryker/oryx-for-zed");
const myCustomZedConfiguration = require("./webpack.config.js");

myCustomZedConfiguration()
  .then((configuration) =>
    oryxForZed.build(configuration, oryxForZed.copyAssets)
  )
  .catch((error) =>
    console.error("An error occurred while creating configuration", error)
  );
  1. Add a script into your package.json pointing to build.js:
{
  "scripts": {
    "build-zed": "node ./path/to/build"
  }
}

API

This section describes API settings.

Settings

oryxForZed.settings;

Contains all the basic settings used in the Webpack configuration. Go to the code for more details.

getConfiguration()

oryxForZed.getConfiguration(settings);

Returns a promise with the default Zed Webpack configuration, based on provided settings. Go to the code for more details.

build()

oryxForZed.build(configuration, callback);

Builds assets using webpack and prints a formatted terminal output. This function is just a wrapper for webpack(configuration, callback):

  • configuration {object}: Webpack configuration file.
  • callback(error, stats) {function} [optional]: Function called once Webpack build task is completed.

copyAssets()

oryxForZed.copyAssets();

Copies public assets to Zed folder for backward compatibility only.

CLI args

oryx-for-zed uses arguments to customize the build process. You can pass them using the terminal:

npm run zed -- --arg

Or embed them into the script section in package.json:

{
  "scripts": {
    "build-zed": "node ./node_modules/@spryker/oryx-for-zed/build --arg"
  }
}

Args list

  • --dev: Development mode; enable webpack watchers on the code
  • --prod: Production mode; enable assets optimization/compression
  • --boost: Boost mode (experimental); build assets using eval source maps

If no arg is passed, development is activated but without watchers.