config
The tool allows you to get a BEM project's settings.
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 BEM project.
An array of options to the libraries used.
An array of options to the modules used.
The level's 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+.
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);
});
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);
});
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);
});
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);
});
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);
});
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);
});
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);
});
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);
});
Async API reference
get()
Returns the extended project configuration merged from:
an optional configuration object from options.defaults;
all configs found by
rcconfiguration file.
const config = require('@bem/sdk.config')();
config.get().then(conf => {
console.log(conf);
});
library()
Returns the library config.
const config = require('@bem/sdk.config')();
config.library('bem-components').then(libConf => {
console.log(libConf);
});
level()
Returns the merged level config.
const config = require('@bem/sdk.config')();
config.level('path/to/level').then(levelConf => {
console.log(levelConf);
});
levels()
Returns an array of levels for the level set.
const config = require('@bem/sdk.config')();
config.levels('desktop').then(desktopSet => {
console.log(desktopSet);
});
levelMap()
Returns all levels hash with their options.
const config = require('@bem/sdk.config')();
config.levelMap().then(levelMap => {
console.log(levelMap);
});
module()
Returns merged config for the required module.
const config = require('@bem/sdk.config')();
config.module('bem-tools').then(bemToolsConf => {
console.log(bemToolsConf);
});
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);
});
Sync API reference
getSync()
Returns the extended project configuration merged from:
an optional configuration object from options.defaults;
all configs found by
rcconfiguration file.
const config = require('@bem/sdk.config')();
const conf = config.getSync();
console.log(conf);
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);
levelSync()
Returns the merged level config.
const config = require('@bem/sdk.config')();
const levelConf = config.levelSync('path/to/level');
console.log(levelConf);
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);
levelMapSync()
Returns all levels hash with their options.
const config = require('@bem/sdk.config')();
const levelMap = config.levelMapSync();
console.log(levelMap);
moduleSync()
Returns merged config for required module.
const config = require('@bem/sdk.config')();
const bemToolsConf = config.moduleSync('bem-tools')
console.log(bemToolsConf);
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);
.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.