@bem/sdk.config

config

This tool allows you to get a BEM project's settings.

• Introduction
• Installation
• Try config
• Quick start
• Options
• Async API reference
• Sync API reference
• .bemrc file example

Introduction

Config allows you to get a BEM project's settings from a configuration file (for example, .bemrc or .bemrc.js).

The configuration file can contain:

• Redefinition levels of the BEM project.
• An array of options for the libraries used.
• An array of options for the modules used.
• The level sets.

Installation

To install the @bem/sdk.config package, run the following command:

$ npm install --save @bem/sdk.config

Try config

An example is available in the RunKit editor.

Quick start

Attention. To use @bem/sdk.config, you must install Node.js 8.0+.

First install the @bem/sdk.config package.

To run the package, follow these steps:

• Include the package in the project.
• Define the project's configuration file.
• Get the project's settings.

Including the @bem/sdk.config package

Create a JavaScript file with any name (for example, app.js) and insert the following:

const config = require('@bem/sdk.config')();

Note. Use the same file for the Getting the project's settings step.

Defining the project's configuration file

Specify the project's settings in the project's configuration file. Put it in the application's root directory.

.bemrc.js file example:

module.exports = {
    // Root directory for traversing `rc` files and collecting configs.
    root: true,
    // Project levels.
    levels: {
        'common.blocks': {},
        'desktop.blocks': {}
    },
    // Modules.
    modules: {
        'bem-tools': {
            plugins: {
                create: {
                    techs: ['css', 'js']
                }
            }
        }
    }
}

Getting the project's settings

Call the asynchronous get() method to get the project's settings.

app.js file:

const config = require('@bem/sdk.config')();
/**
 * Config is a merge of:
 * - an optional configuration object (see `options.defaults`);
 * - all configs found by `rc` configuration files.
 **/
config.get().then((conf) => {
    console.log(conf);
});
/**
 *
 * {
 *   root: true,
 *   levels: [
 *     {path: 'common.blocks'},
 *     {path: 'desktop.bundles'}],
 *   modules: {
 *      'bem-tools': {plugins: {create: {techs: ['css', 'js']}}}},
 *   __source: '.bemrc'
 * }
 *
 **/

Options

Config options listed below can be used to create settings for the config itself. They are optional.

const config = require('@bem/sdk.config');
/**
 * Constructor.
 * @param {Object} [options] — Object.
 * @param {String} [options.name='bem'] — Config filename. `rc` is appended to the filename, and the config traverses files with this name with any extension (for example `.bemrc`, `.bemrc.js`, `.bemrc.json`).
 * @param {String} [options.cwd=process.cwd()] — Project's root directory.
 * @param {Object} [options.defaults={}] — Found configs are merged with this object.
 * @param {String} [options.pathToConfig] — Custom path to the config in FS via the `--config` command line argument.
 * @param {String} [options.fsRoot] — Custom root directory.
 * @param {String} [options.fsHome] — Custom `$HOME` directory.
 * @param {Object} [options.plugins] — An array of paths to the required plugins.
 * @param {Object} [options.extendBy] — Extensions.
 * @constructor
 */
const bemConfig = config([options]);

• options.name
• options.cwd
• options.defaults
• options.pathToConfig
• options.fsRoot
• options.fsHome
• options.plugins
• options.extendBy

options.name

Sets the configuration filename. The default value is bem.

Example:

const config = require('@bem/sdk.config');
const bemConfig = config({name: 'app'});
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.cwd

Sets the project's root directory. The name of the desired resource relative to your app root directory.

Example:

const config = require('@bem/sdk.config');
const bemConfig = config({cwd: 'src'}); // Put the `rc` file into the `src` folder.
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.defaults

Sets the additional project configuration.

Example:

const config = require('@bem/sdk.config');
const optionalConfig = { defaults: [{
    levels: {
            'common.blocks': {},
            'desktop.blocks': {}
        }
    }
]};
const projectConfig = config(optionalConfig);
projectConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.pathToConfig

Sets the custom path to the config in file system via the --config command line argument.

Example:

const config = require('@bem/sdk.config');
const bemConfig = config({pathToConfig: 'src/configs/.app-rc.json'});
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.fsRoot

Sets the custom root directory. The path to the desired resource is relative to your app root directory.

Example:

const config = require('@bem/sdk.config');
const bemConfig = config({fsRoot: '/app', cwd: 'src/configs'});
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.fsHome

Sets the custom $HOME directory.

Example:

const config = require('@bem/sdk.config');
const bemConfig = config({fsHome: 'src'});
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.plugins

Sets the array of paths to the required plugins.

Example:

const config = require("@bem/sdk.config");
const optionalConfig = { defaults: [{ plugins: { create: { techs: ['styl', 'browser.js']}}}]};
const bemConfig = config(optionalConfig);
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

options.extendBy

Sets extensions.

Example:

const config = require('@bem/sdk.config');
const bemConfig = config({
    extendBy: {
        levels: [
            { path: 'path/to/level', test: 1 }
        ],
        common: 'overriden',
        extended: 'yo'
    }
});
bemConfig.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

Async API reference

get()

Returns the extended project configuration merged from:

• an optional configuration object from options.defaults;
• all configs found by the rc configuration file.

const config = require('@bem/sdk.config')();
config.get().then(conf => {
    console.log(conf);
});

RunKit live editor.

library()

Returns the library config.

const config = require('@bem/sdk.config')();
config.library('bem-components').then(libConf => {
    console.log(libConf);
});

RunKit live editor.

level()

Returns the merged level config.

const config = require('@bem/sdk.config')();
config.level('path/to/level').then(levelConf => {
    console.log(levelConf);
});

RunKit live editor.

levels()

Returns an array of levels for the set of levels.

const config = require('@bem/sdk.config')();
config.levels('desktop').then(desktopSet => {
    console.log(desktopSet);
});

RunKit live editor.

levelMap()

Returns a hash of all levels with their options.

const config = require('@bem/sdk.config')();
config.levelMap().then(levelMap => {
    console.log(levelMap);
});

RunKit live editor.

module()

Returns merged config for the required module.

const config = require('@bem/sdk.config')();
config.module('bem-tools').then(bemToolsConf => {
    console.log(bemToolsConf);
});

RunKit live editor.

configs()

Returns all found configs from all dirs.

Note. It is a low-level method that is required for working with each config separately.

const config = require('@bem/sdk.config')();
config.configs().then(configs => {
    console.log(configs);
});

RunKit live editor.

Sync API reference

getSync()

Returns the extended project configuration merged from:

• an optional configuration object from options.defaults;
• all configs found by the rc configuration file.

const config = require('@bem/sdk.config')();
const conf = config.getSync();
console.log(conf);

RunKit live editor.

librarySync()

Returns the path to the library config. To get the config, use the getSync() method.

const config = require('@bem/sdk.config')();
const libConf = config.librarySync('bem-components');
console.log(libConf);

RunKit live editor.

levelSync()

Returns the merged level config.

const config = require('@bem/sdk.config')();
const levelConf = config.levelSync('path/to/level');
console.log(levelConf);

RunKit live editor.

levelsSync()

Returns an array of level configs for the set of levels.

Note. This is a sync function because we have all the data.

const config = require('@bem/sdk.config')();
const desktopSet = config.levelsSync('desktop');
console.log(desktopSet);

RunKit live editor.

levelMapSync()

Returns a hash of all levels with their options.

const config = require('@bem/sdk.config')();
const levelMap = config.levelMapSync();
console.log(levelMap);

RunKit live editor.

moduleSync()

Returns the merged config for the required module.

const config = require('@bem/sdk.config')();
const bemToolsConf = config.moduleSync('bem-tools')
console.log(bemToolsConf);

RunKit live editor.

configs()

Returns all found configs from all dirs.

Note. It is a low-level method that is required for working with each config separately.

const config = require('@bem/sdk.config')();
const configs = config.configs(true);
console.log(configs);

RunKit live editor.

.bemrc file example

Example of the configuration file:

module.exports = {
    // Root directory.
    'root': true,
    // Project levels. Override common options.
    'levels': [
        {
            'path': 'path/to/level',
            'scheme': 'nested'
        }
    ],
    // Project libraries.
    'libs': {
        'libName': {
            'path': 'path/to/lib'
        }
    },
    // Sets.
    'sets': {
        // Will use the `touch-phone` set from bem-components and a few local levels.
        'touch-phone': '@bem-components/touch-phone common touch touch-phone',
        'touch-pad': '@bem-components common deskpad touch touch-pad',
        // Will use the `desktop` set from `bem-components` and also a few local levels.
        'desktop': '@bem-components common deskpad desktop',
        // Will use a mix of levels from the `desktop` and `touch-pad` sets from `core`, `bem-components` and locals.
        'deskpad': 'desktop@core touch-pad@core desktop@bem-components touch-pad@bem-components desktop@ touch-pad@'
    },
    // Modules.
    'modules': {
        'bem-tools': {
            'plugins': {
                'create': {
                    'techs': [
                        'css', 'js'
                    ],
                    'templateFolder': 'path/to/templates',
                    'templates': {
                        'js-ymodules': 'path/to/templates/js'
                    },
                    'techsTemplates': {
                        'js': 'js-ymodules'
                    },
                    'levels': [
                        {
                            'path': 'path/to/level',
                            'techs': ['bemhtml.js', 'trololo.olo'],
                            'default': true
                        }
                    ]
                }
            }
        },
        'bem-libs-site-data': {
            'someOption': 'someValue'
        }
    }
}

License

© 2019 Yandex. Code released under Mozilla Public License 2.0.