EN RU
Форум

Методология

Технологии

Инструментарий

Библиотеки

Учебные материалы

Перевод этой статьи на ваш язык отсутствует, вы можете помочь нам перевести.

config

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

NPM Status

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:

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+.

Use the following steps after installing the package.

To run the @bem/sdk.config package:

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 step Getting the project's settings.

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 an asynchronous method get() 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. The config options can be used to make settings for the config itself. Options are optional and listed below.

const config = require('@bem/sdk.config');
/**
 * Constructor.
 * @param {Object} [options] — Object.
 * @param {String} [options.name='bem'] — Config filename. This option is converted to `rc` file and config traverse different variations of file formats (for example `.bemrc`, `.bemrc.js`, `.bemrc.json`).
 * @param {String} [options.cwd=process.cwd()] — Project's root directory.
 * @param {Object} [options.defaults={}] — Use this object as fallback for found configs.
 * @param {String} [options.pathToConfig] — Custom path to config on FS via command line argument `--config`.
 * @param {String} [options.fsRoot] — Custom root directory.
 * @param {String} [options.fsHome] — Custom `$HOME` directory.
 * @param {Object} [options.plugins] — An array of paths to plugins to require.
 * @param {Object} [options.extendBy] — Extensions.
 * @constructor
 */
const bemConfig = config([options]);

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'}); // You should put `rc` file to `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 config on file system via command line argument --config.

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 plugins to require.

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:

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 level set.

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

RunKit live editor.

levelMap()

Returns all levels hash 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:

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. To get config, use 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 levels configs for the level set.

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 all levels hash with their options.

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

RunKit live editor.

moduleSync()

Returns merged config for 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 `touch-phone` set from bem-components and few local levels.
        'touch-phone': '@bem-components/touch-phone common touch touch-phone',
        'touch-pad': '@bem-components common deskpad touch touch-pad',
        // Will use `desktop` set from `bem-components`, and also few local levels.
        'desktop': '@bem-components common deskpad desktop',
        // Will use mix of levels from `desktop` and `touch-pad` level 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.