@borngroup/born-build

Build tool for storefronts

Usage no npm install needed!

<script type="module">
  import borngroupBornBuild from 'https://cdn.skypack.dev/@borngroup/born-build';
</script>

README

BORN build process with Revolver

There are different scenarios covered by Revolver when working on a project with single or multiple store configurations. Revolver adapts to your setup depending on the parameters passed and which files are available.

Multiple stores configurations with either a main or independent store cartridge(s):

Let’s say you have multiple stores and each has its own styles and own set of JS. To build the default store, all you need to run is:

npm run [task]

To build a specific store or cartridge, run:

npm run [task] --env.cartridge=cartridge_name

Note: replace “[task]” with the task you want to run, such as build or watch.

Now let's say you need your "main_cartridge" to leverage almost all of the JS functionality from your "base_cartridge". However, you'd like to modify a few files in your "main_cartridge" without having to copy all of the source code from "base_cartridge". You can achieve this by setting the revolverPath property on your package.json to follow the priority you need:

"scripts":  {
    [...]
},
"config":  {
    "cartridge": “main_cartridge”,
    "js": {
        "revolverPath": "main_cartridge, base_cartridge"
    }
}

Then simply run:

npm run [task]

This also works if you need to build a specific cartridge. Your revolverPath needs to include the extra cartridge:

"revolverPath": "cartridge_name, main_cartridge, base_cartridge"

And then you can run:

npm run [task] --env.cartridge=cartridge_name

You can override the resolverPath value at run time by passing it as a parameter:

npm run [task] --env.revolverPath=third_cartridge,fourth_cartridge

You can run parallel builds by specifying a list of cartridges on the cartridge variable:

npm run [task] --env.cartridge=main_cartridge,second_cartridge,third_cartridge

Note: When running a command, use commas and no spaces between cartridge names. This is a limitation with Node.

Each cartridge must have at least one app.js file (inside the js/ or js/born/ directories, or both). Otherwise it means this cartridge is not meant to host built files, so the build will dump the files into the cartridge specified in config.cartridge instead.

Single store with single or multiple locales:

Create a style.scss file inside the respective locale. If you have more than one locale, @import all the partials you need from the default or specific locale, then just replace those that are different for your current locale.

Run:

npm run [task]

This assumes you've setup a default cartridge and an optional set of styles.inputPath and styles.outputPath (defaults to "cartridges/{cartridge}/cartridge/scss/**/*.scss" and "cartridges/{cartridge}/cartridge/static/{subDirectory}/css/{outputFile}.css" respectively) on your package.json

"scripts":  {
    [...]
},
"config":  {
    "cartridge": “your_main_cartridge”,
    "styles": {
      "inputPath": "cartridges/{cartridge}/cartridge/scss/**/*.scss",
      "outputPath": "cartridges/{cartridge}/cartridge/static/{subDirectory}/css/{outputFile}.css"
    }
},
"devDependencies": {
    [...]
}

Styles object:

|Property|Description| |--|--| |inputPath|(optional) is the input path to your .scss files. The string uses a combination of interpolation and glob's magic patterns to determine the exact file that needs to be parsed. This property accepts a dynamic value for the {cartridge}.|
|outputPath|(optional) is the output path of your built .css files. The string works similar to styles.inputPath, but in addition to having a {cartridge} dynamic value, you can also format your string using the {subDirectory} and {outputFile} values.|

Styles object dynamic values:

|Value|Description| |--|--| |{cartridge}|It's value gets replaced with the cartridge name being processed during build time. For example, if you pass --env.cartridge=your_main_cartridge,your_second_cartridge, then the value of {cartridge} will become each of the specified cartridges| |{subDirectory}|It's value will be equal to the sub-directory found by the build when expanding the glob pattern in the styles.inputPath, if any. For example, say your inputPath is "cartridges/{cartridge}/cartridge/scss/**/*.scss", which then becomes "cartridges/your_main_cartridge/cartridge/scss/en_US/main-styles.scss". In this example, the value of {subDirectory} will be "en_US". Note: Because CSS url references are relative to the file's location, built .css files will be placed in the specified output directory and will not carry their input sub-directory structure, other than the base {subDirectory}.| |{outputFile}|It's value will be equal to the file name found by the build when expanding the glob pattern in the styles.inputPath, if any. For example, say your inputPath is "cartridges/{cartridge}/cartridge/scss/**/*.scss", which then becomes "cartridges/your_main_cartridge/cartridge/scss/en_US/main-styles.scss". In this example, the value of {subDirectory} will be "main-styles".|