Oryx for Zed

Edit on GitHub

Introduction

oryx-for-zed is an extension of Oryx 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/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 version >=12.0.0
  • npm version >=6.9.0

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
# or
yarn add @spryker/oryx-for-zed --dev

oryx-for-zed comes with a peer dependency: oryx version >= 1.x.

Usage

Once installed, you can:

  • call the builder directly from your scripts (simple builder)
  • extend/change the settings/webpack configuration for your custom Zed build

Simple builder

The following section describes how to run oryx-for-zed. Add the following script to your package.json:

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

Open the terminal and type:

npm run build-zed
# or
yarn run build-zed

Extend or change the settings

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

The example below shows how to create a custom build:

Step 1: build.js
Create a build.js file in your project containing your custom settings and the logic needed to get the webpack configuration and run the builder:

const oryx = require("@spryker/oryx");
const oryxForZed = require("@spryker/oryx-for-zed");

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

oryxForZed
  .getConfiguration(myCustomZedSettings)
  .then((configuration) => oryx.build(configuration));

Step 2: package.json
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/change webpack configuration

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

The example below shows how to create a custom build:

Step 1: webpack.config.js
Create a webpack.config.js file in your project containing your Webpack custom configuration:

const oryxForZed = require("@spryker/oryx-for-zed");

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

  return Object.assign({}, oryxConfiguration, {
    // your own configuration
  });
}

Step 2: build.js
Create a build.js file in your project containing your Webpack configuration and the logic needed to run the builder:

const oryx = require("@spryker/oryx");
const myCustomZedConfiguration = require("./webpack.config.js");

myCustomZedConfiguration().then((configuration) => oryx.build(configuration));

Step 3: package.json
Add a script into your package.json pointing to build.js:

{
  "scripts": {
    "build-zed": "node ./path/to/build"
  }
}

API

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.

CLI args

oryx-for-zed uses arguments to customize the build process.

You can pass them using the terminal:

npm run zed -- --arg
# or
yarn 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.