Webpack: Cartridge Resolver Plugin

Provide the cartridge inheritance behavior same as Demandware server side scripts with additional functionalities supports.

Installation

npm install --save-dev @midiu/cartridge-resolver

Usage

Register plugin to your webpack.config.js. For more informations, please have a look inside class CartridgeResolverPlugin

const cwd = process.cwd();
const CartridgeResolverPlugin = require('@midiu/cartridge-resolver');

module.exports = {
    // your other webpack configs...
    resolve: {
        plugins: [new CartridgeResolverPlugin({
            your_storefront: path.resolve(cwd, 'cartridges/your_storefront/cartridge/client'),
            your_storefront_style_guide: path.resolve(cwd, 'cartridges/your_storefront_style_guide/cartridge/client'),
            plugin_wishlists: path.resolve(cwd, 'vendors/plugin_wishlists/cartridge/client'),
            app_storefront_style_guide: path.resolve(cwd, 'cartridges/app_storefront_style_guide/cartridge/client'),
            app_storefront_core: path.resolve(cwd, 'cartridges/app_storefront_core/cartridge/client'),
            app_storefront_base: path.resolve(cwd, 'cartridges/app_storefront_base/cartridge/client')
        }, {
            base: 'app_storefront_base',
            core: 'app_storefront_core'
        })]
    }
}

Asset Solving Rules

+ ----------- + ----- + --------------------------- +
| Cartridge   | Alias |            Assets           |
+ ----------- + ----- + --- - --- - --- - --- - --- +
| cartridge_a |   a   |  1  |     |  3  |     |  5  |
| cartridge_b |   b   |     |  2  |  3  |  4  |     |
| cartridge_c |       |     |     |     |  4  |  5  |
| cartridge_d |   d   |  1  |  2  |     |     |  5  |
+ ----------- + ----- + --------------------------- +

1. Cartridge lookup priority follow the order of registered cartridges object ASC.
2. Use special symbols to require the target asset.
   1. ^ flag used to lookup super module asset, Example:
      • require('^') - require same asset from lower priority cartridges
      • require('^/some/asset') - require some/asset from lower priority cartridges
      • require('^:some/asset') - same as above, require some/asset from lower priority cartridges
   2. * flag used to lookup across registered cartridges
      • require('*/some/asset') - require some/asset from any cartridges
      • require('*:some/asset') - same as above, require some/asset from any cartridges
   3. ~ flag used to lookup asset in current cartridge
      • require('~/some/asset') - require some/asset from current cartridge
      • require('~:some/asset') - same as above, require some/asset from current cartridge
3. superModule are modules loaded from lower priority cartridges . For example: in cartridge_b:2.js, require super module mean lookup for asset 2.js in 2 other lower priority cartridge_c and cartridge_d. The result will be cartridge_d:2.js
4. Absolute cartridge can be used follow pattern: {cartridge_name}:{asset_path} or {alias_name}:{asset_path}. Solving the asset_path from exactly cartridge_name or alias_name. For example:
   • require('cartridge_d:1') will return cartridge_d/1.js
   • require('c:5') will return cartridge_c/5.js
5. Named alias asset:
   1. difference path with origin will be solve using asterisk * behavior. For example:
      • From cartridge_a/1.js - require('d/2') which looking for 2.js using d alias (difference path with origin 1.js) will equal require('*/2') and return cartridge_b/2.js (since the cartridge_b has higher priority than cartridge_d)
      • From cartridge_b/2.js - require('c/5') which looking for 5.js using c alias (difference path with origin 2.js) will equal require('*/5') and return cartridge_a/5.js (since the cartridge_a has higher priority than cartridge_c)
   2. same path with origin will be solve using super module ^ behavior: For example:
      • From cartridge_a/1.js - require('a/1') which looking for 1.js using a alias (same path with origin 1.js) will equal require('^/1') and return cartridge_d/1.js
6. By default, an asset will be lookup across cartridges and return the fist found. Except super module and absolute cartridge path. For example: in cartridge_a:1.js, require relative ./2 asset will return the first asset found from cartridge path. The result will be cartridge_b:2.js
7. Required asset same path with the origin will considered as super module. For example: in cartridge_a:1.js, all requirements require('^') or require('^:1') or require('^/1') or require('.') or require('./1') will looking for 1.js from lower priority cartridges . The result will be cartridge_d:1.js