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 1 commit
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
42 changes: 42 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,48 @@

## Usage

### `.bemrc` fields

Field | Type | Purpose
--- | --- | ---
root | `Boolean` | Used to determine the root directory from the current one
Copy link
Collaborator

Choose a reason for hiding this comment

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

Can you explain this? May be with an example

naming | `string`, `Object` | Name of existing in [`naming.preset`](https://github.com/bem/bem-sdk/tree/master/packages/naming.presets) preset or custom definition
Copy link
Collaborator

Choose a reason for hiding this comment

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

"Name of one of [naming.presets] or custom preset definition" is better for me

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 use in projects
Copy link
Collaborator

Choose a reason for hiding this comment

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

Levels/layers again :) What is layer? Why do we declare levels not layers above?

Copy link
Collaborator

Choose a reason for hiding this comment

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

"to use in projects" > "to build" is better I think

Copy link
Member Author

Choose a reason for hiding this comment

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

Layer is a property of a level. So we defining all levels but use just some.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Good example with images at methodology will help I think

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
Copy link
Collaborator

Choose a reason for hiding this comment

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

reference "how/where .module is used" to docs or example is required


#### `LevelConf`

Describes level with sources.
Copy link
Collaborator

Choose a reason for hiding this comment

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

level > redefinition level + link to methodology article

In classic version it represents a directory for a single layer — e.g. `bem-components/common.blocks/` for `common` or `bem-components/desktop.blocks/` for `desktop`.
In modern version represents a set of layers relative to library path (`.bemrc` location)
and depends on naming preset — e.g. `common` and `desktop` for just `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.

More text is needed. May be example can help or methodology article somewhere in https://en.bem.info/methodology/


- `layer` - name of level‘s layer to use in sets
Copy link
Collaborator

Choose a reason for hiding this comment

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

sets > sets option OR SetConf

- `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. required for legacy way, unwanted for the modern one
- the rest fields will have passed to level config
Copy link
Collaborator

Choose a reason for hiding this comment

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

We need to explain why do someone need other fields


#### `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` - to library which should better contain their own `.bemrc` file with their own sets
- the rest fields will have 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.

path - path (repeating is okey) to library. Library should contain its own .bemrc file. If omitted path is evaluated to node_modules/${libraryName} (shorted sentences are more readable)


#### `PluginConf`

- all the fields will have passed directly to plugins

## API

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