Storefront Reference Architecture (SFRA) Recipes

SFRA recipes allow the automation of git repositories configuration via the recipe command.

This repository contains "official" recipes for git repositories endorsed by the Midiu Core Team. For contributed recipes, see the contrib repository section.

Creating Recipes

SFRA recipes consist of a manifest.js config file and, optionally, any number of files and directories. Recipes must be stored on their own repositories, outside of your git repository. They must follow the {vendor}/{package}/{version} directory structure, where version is the minimum version supported by the recipe.

The following example shows the real directory structure of some SFRA recipes:

cartridges/
    app-storefront-base/
        0.7/
            manifest.js
        2.0/
            manifest.js
        manifest.js
    manifest.js
modules/
    server/
        0.7/
            manifest.js
        2.0/
            manifest.js
        manifest.js
    manifest.js

The manifest.js file contents are divided into options, tasks and configurators. The url option in both source and target are required fields. All other fields are optional.

Context

• sourcePath - Full path to source git repository
• targetPath - Full path to target git repository
• recipePath - Full path to recipe component. Eg: recipes
• modulePath - Full path to current component. Eg: recipes/cartridges/app-storefront-base
• manifestPath - Full path to current manifest version. Eg: recipes/cartridges/app-storefront-base/2.1.0
• version - Current tagged code version. Eg: v3.3.0
• scope - Scope name of current package. Eg: midiu
• gitHost - Git host name. Eg: github.com or bitbutcket.org
• gitOwner - Git user name. Eg: midiu
• copyrightHolder - Contains copyright holder name and email, used for LISENCE. Eg: Vinh Trinh <[email protected]>

Options

source Option

This option defines the name and url of source repository that will be used to sync the contents to target repository. The name option is optional and will be used as local directory when clone git repository using required url option. If the name option is omitted, the vendor name and package name will be extracted from url option.

{
    "source": {
        "name": "@{scope}/{package}",
        "url": "git@{gitHost}:{gitOwner}/{package}.git"
    }
}

target Option

Similar to source option, this option defines the name and url of target repository that will be used to store contents from source repository. Basically, the target repository is your repository. The name option and url option are complete same as source option above.

{
    "target": {
        "name": "@{vendor}/{package}",
        "url": "git@${gitHost}:{vendor}/{package}.git"
    }
}

Tasks

There are several types of tasks: copy, delete, rsync and filterPackageConfigs.

copy Task

To be implemented

Copies files or directories from the source git repository to the target git reposiroty. It's defined as an associative object where the key is the original file/directory and the value is the target file/directory. It's useful to copy the initial configuration of the dependency and even a simple initial structure of files and directories:

This example copies the package.json file from root source git reposiroty to root target reposiroty:

{
    copy: {
        './package.json': '.'
    }
}

// ...is similar to
{
    copy: {
        `${sourcePath}/package.json`: `${targetPath}`
    }
}

The sourcePath and targetPath are special values that it's turned into the absolute paths of source and target directories. These are the special variables available: sourcePath, targetPath and recipePath.

rsync Task

To be implemented

filterPackageConfigs Task

To be implemented

Configurators

There are several types of tasks: gitignore, npmignore and package.

gitignore Configurator

Adds patterns to the .gitignore file of the target git repository. Define those patterns as a simple array of strings:

{
    gitignore: [
        '.DS_Store',
        '.develop',
        '.gitmodules',
        '.idea',
        '.vscode',
        'dw.json',

        'node_modules',

        'cartridge/static/*/css',
        'cartridge/static/*/fonts',
        'cartridge/static/*/js'
    ]
}

Similar to other configurators, the contents are copied into the .gitignore file and wrapped with section separators (### begin: your-recipe-name and ### end: your-recipe-name) that must not be removed or modified.

### begin: your-recipe-name
.DS_Store
.develop
.gitmodules
.idea
.vscode
dw.json

node_modules

cartridge/static/*/css
cartridge/static/*/fonts
cartridge/static/*/js
### end: your-recipe-name

npmignore Configurator

Adds patterns to the .npmignore file of the target git repository. Define those patterns as a simple array of strings:

{
    npmignore: [
        '.DS_Store',
        '.build',
        '.develop',
        '.gitignore',
        '.gitmodules',
        '.idea',
        '.project',
        '.tern-project',
        '.vscode',
        '*.md',
        '*.zip',

        'dw.json',
        'package-lock.json',

        'cartridge/recipesent/**',
        'cartridge/recipesent/**'
    ]
}

Similar to other configurators, the contents are copied into the .npmignore file and wrapped with section separators (### begin: your-recipe-name and ### end: your-recipe-name) that must not be removed or modified.

### begin: your-recipe-name
.DS_Store
.build
.develop
.gitignore
.gitmodules
.idea
.project
.tern-project
.vscode
*.md
*.zip

dw.json
package-lock.json

cartridge/recipesent/**
cartridge/recipesent/**
### end: your-recipe-name

package Configurator

Adds new package parameters in the package.json file by adding your parameters in the package configurator. All parameters configured in package configurator will be merged to package.json file using _.merge method.

This example creates a new dependencies parameter with lodash package with used but missed dependencies in source repository:

{
    package: {
        dependencies: {
            lodash: '^4.17.11'
        }
    }
}

Full Example

Combining all the above configurators you can define powerful recipes, like the one used by cartridges/app-storefront-base:

module.exports = {
    // Optionators
    source: {
        name: `@salesforce/storefront-reference-architecture`,
        url: `[email protected]:SalesforceCommerceCloud/storefront-reference-architecture.git`
    },
    target: {
        name: `@${vendor}/app-storefront-base`,
        url: `git@${gitHost}:${vendor}/cartridge-app-storefront-base.git`
    },

    // Tasks
    copy: {
        './package.json': '.'
    },
    delete: [
        './.tern-project'
    ],
    rsync: {
        './app_storefront_base/': '.'
    },
    filterPackage: ['name', 'version', 'description', 'author', 'license', 'homepage', 'dependencies', 'dw', 'hooks'],

    // Configurators
    gitignore: [
        '.DS_Store',
        '.idea',
        '.gitmodules',
        '.develop',
        '.vscode',
        'dw.json',

        'node_modules',

        'cartridge/static/*/css',
        'cartridge/static/*/fonts',
        'cartridge/static/*/js'
    ],
    npmignore: [
        '.DS_Store',
        '.build',
        '.develop',
        '.gitignore',
        '.gitmodules',
        '.idea',
        '.project',
        '.tern-project',
        '.vscode',
        '*.md',
        '*.zip',

        'dw.json',
        'package-lock.json',

        'cartridge/recipesent/**',
        'cartridge/recipesent/**'
    ],
    package: {
        name: `@${vendor}/app_storefront_base`,
        version: '{version}',
        description: 'SFRA: App Storefront Base',
        dependencies: {
            'lodash': '^4.17.11'
        },
        dw: {
            alias: ['base'],
            tasks: {
                js: true,
                scss: true,
                copy: {
                    patterns: [{
                        from: './node_modules/flag-icon-css/flags',
                        to: '${cartridge.staticPath}/default/fonts/flags',
                        toType: 'dir'
                    }, {
                        from: './node_modules/font-awesome/fonts',
                        to: '${cartridge.staticPath}/default/fonts',
                        toType: 'dir'
                    }]
                }
            }
        }
    }
}

Contributing

For more information about contributing a recipe, read the documentation on the main repository.

Unlike for official recipes, the pull requests for new contrib recipes are reviewed by the Core Merger and merged when the following conditions are met (in that order):

• manifest.js file must be valid
• manifest.js file must use 4 space indentations
• JSON files must be valid
• JSON files must use 4 space indentations
• The package repository must exist
• The package repository must have at least one tagged version
• All text files should end with a newline
• All files are stored under a directory referenced by the copy section of manifest.js