Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

config: describe the main fields #284

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

config: describe the main fields #284

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a7db60f
docs(config): describe the primary set of fields in .bemrc
qfox Feb 13, 2018
8213d50
fixup! docs(config): describe the primary set of fields in .bemrc
tadatuta Feb 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions packages/config/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,74 @@

## Usage

### `.bemrc` fields

Field | Type | Purpose
--- | --- | ---
root | `Boolean` | Used to determine the root directory. Configs in parent dirs won't be gathered
naming | `string`, `Object` | Name of one of [naming presets](https://github.com/bem/bem-sdk/tree/master/packages/naming.presets) or custom naming definition
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And default value?

levels | `Array<LevelConf>` | List of known levels in the right order<br> (usually local) with their configurations
Copy link
Member Author

@qfox qfox Mar 24, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feels like we don't need the difference between levels and libraries — in all cases they are the same.

Let's drop this field in favor of layerOrder: string[] since we need to only to define ordering between layers for now and it's almost useless logic for the most of our users.

If we need to configure some directory (originally levels) with additional fields we should convert them to libraries and define in libs field. path there would start with './' as it does in nodejs's require function so it will be very familiar too.

So:

  • Dropping levels
  • Adding layerOrder
  • Filtering libraries, if need to get local ones (configured "levels")

cc @blond @tadatuta

sets | `Object<string, SetConf>` | Named sets of layers to build
libs | `Object<string, LibraryConf>` | Dependency libraries to use in sets
plugins | `Object<string, PluginConf>` | Various configurations for plugins,<br>can be reached via [`.module`](#module) method

#### `root`

For the following file structure
```
/
projects/
prj1/
.bemrc
.bemrc
.bemrc
```
and `/projects/prj1/` as current working directory `root` option set to `true` in `/projects/prj1/.bemrc` will prevent `bem-config` to collect data from `/projects/.bemrc` and `/.bemrc`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Too complicated. We shall to come up with basic process of bem/sdk-config walking file system and collecting bemrc.

Start with more realistic example:

project/
  src/
  libs/
    fooLib/
      .bemrc
  .bemrc

And tell "config of project contains of two .bemrc" and define merge algorithm. After it we can explain things like root-property


#### `LevelConf`

Describes [redefinition level](https://en.bem.info/methodology/key-concepts/#redefinition-level) with sources — a set of layers relative to library path (`.bemrc` location)
and depends on naming preset. E.g. `common` and `desktop` for `bem-components/` (library) path and [`origin`](https://github.com/bem/bem-sdk/blob/master/packages/naming.presets/origin.js) preset.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"a set of layers relative to library path (...)" - is very good.

The second part is not. Can we simply add some examples:

{ layer: 'common', path: 'foo/bar' } defines set of one layer with relative path 'foo/bar'
{ layer: 'common' } defines set of layers depending on naming. Relative paths can be 'common.blocks/', 'blocks-common', etc.

Am I right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right.

We want to merge levels into libraries (as it is semantically the same) but @tadatuta worries about classic definition of level.
What you think if we just move this part to the library description with any custom fields?


Usualy it represents a directory for a single layer — e.g. `bem-components/common.blocks/` for `common` or `bem-components/desktop.blocks/` for `desktop`.

- `layer` - name of level‘s layer to use in `sets` option
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guess we don't need to write level's here. No one should care about level in new paradigm

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

level's → semantic

- `naming` - naming preset for this level
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is default value here? Root naming?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guess, it should be 'origin'. Let's write here about it if no one against

- `path` - optional, deprecated. Required for legacy way, unwanted for the modern one
- the rest fields will be passed to level config (if required by some custom consumer)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, it's deprecated... So example above is bad idea. Can we put properties in a table | Field | Property | Type | ?


##### Example
```js
{
"levels": [
{
"layer": "common",
"naming": "origin",
"scheme": "nested"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

scheme? Is it an example of custom property? Can we add a comment for it?

}
]
}
```

#### `SetConf`

`string|Array<string|{library: string, set?: string}>`

One of:
- single string with all used layers; e.g. `'bem-core@ common deskpad desktop'`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mistake. Right form is @bem-core

- list of layers and/or libraries and library sets; e.g. `[{library: 'bem-core'}, 'common', 'deskpad', 'desktop']`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please add variant with library and set in one item

Copy link
Member Author

@qfox qfox Feb 14, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, if set is undefined then the current one will be used by default.
Not sure how to show it in one sentence

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your definition "if set is undefined then the current one will is used by default" is okey. Write more short sentences

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this version we missed 'bem-core@desktop' and { library: 'bem-core', layer: 'desktop' }

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"targets specific layer in library"


#### `LibraryConf`

- `path` - path (repeating is okey) to library. Library should contain its own .bemrc file. If omitted path is evaluated to node_modules/${libraryName}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please put bemrc and node_modules/... in ticks

- the rest fields will be passed to library config and extend `.bemrc` config found at `${path}/.bemrc`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems it is not true. librarySync for example computes cwd from LibraryConf only


#### `PluginConf`

- all the fields will be passed directly to plugins
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What plugins? Can we add an example?


## API

```js
const bemConfig = require('@bem/sdk.config');
const optionalConfig = { plugins: { create: { techs: ['styl', 'browser.js'] } } };
Expand Down