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.
@bem/sdk.config
package
Including the 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);
});
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);
});
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 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);
});
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 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);
});
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 the
rc
configuration 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 set of levels.
const config = require('@bem/sdk.config')();
config.levels('desktop').then(desktopSet => {
console.log(desktopSet);
});
levelMap()
Returns a hash of all levels 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 the
rc
configuration file.
const config = require('@bem/sdk.config')();
const conf = config.getSync();
console.log(conf);
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);
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 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);
levelMapSync()
Returns a hash of all levels with their options.
const config = require('@bem/sdk.config')();
const levelMap = config.levelMapSync();
console.log(levelMap);
moduleSync()
Returns the merged config for the 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 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.