mendel-config v4.0.0-alpha.3

Mendel Config

This is an internal package that helps Mendel normalize configuration defaults, on .mendelrc or on package.json. It is used by many Mendel packages to make sure all packages use the same defaults and same merging logic.

API

var configParser = require('mendel-config');

// passing no options will lookup `.mendelrc` or `package.json` in the current
// folder and parent folders recursively. If not found returns default config.
var config = configParser();

// passing `basedir` as string or as property will make mendel lookup
// `.mendelrc` or `package.json` in the target folder instead.
var config = configParser('./sub/folder/config');

// which is equivalent to:
var config = configParser({ basedir: './sub/folder/config' });

// programmatic config only
var config = configParser({
    config: false, // prevent looking for `.mendelrc` or `package.json`
    // any other valid config
});

// Lookup `.mendelrc` or `package.json` and override a few params
var config = configParser({
    // any valid config, except config:false
});

Configuration parsing happens in 3 steps:

1. Merging by precedence:

Configuration precedence is, from order to strongest to weakest:

1. Passing configuration as an JavaScript object
2. Configuration on .mendelrc or package.json
3. Mendel defaults

The only exception is basedir. basedir has different meanings depending on where you declare it:

1. If basedir is passed programmatically it is meant as a configuration lookup folder
2. If any of .mendelrc or package.json is found, basedir is forced to be the folder that contains the config file, even if you provide one as property of the configuration object.
3. All other path entries that are not absolute will be relative to basedir

2. Merging by environment

Either process.env.MENDEL_ENV or process.env.NODE_ENV values can be used to configure overrides on .mendelrc.

3. Resolving relative paths

After parsing and merging all the configurations a number of path properties will be resolved relative to basedir or their "parent" configuration, for example bundlesoutdir is relative to outdir which is in place relative to basedir. Please refer to .mendelrc file configuration documentation to a full list.

4. Parsing bundles

In .mendelrc or package.json the bundles entry is an object, we will transform bundles into an array and lastly the following arrays will be flattened: entries, require, external, exclude, ignore.

Flattening is useful to use YAML references to manipulate the file lists. For example, the logged_in_bundle bellow will have all files from vendor and from main, since arrays are flattened:

# Mendel v2

build-dir: ./build

# Base/default variation configuration
base-config:
    id: base
    dir: ./src/master

variation-config:
    variation-dirs:
        - ./src/environments
        - ./src/settings
        - ./src/experiments
        - ./src/themes
    # dir names should be unique across all roots or mendel throws
    variations:
        # id of variation
        button_color:
            # name of the folder
            - blue_button

route-config:
    variation: /mendel/:variations/:bundle
    hash: /mendel/:hash/:bundle

transforms: # a list of all available transforms for all envs and types
    babelify-dev:
        plugin: mendel-babelify
        options:
            plugins:
                - - react-intl
                  - messagesDir: ./tmp/strings/
                    enforceDescriptions: true
    babelify-prod:
        plugin: mendel-babelify
        options:
            plugins:
                - react-intl-remove-description
                - transform-react-remove-prop-types
                - - react-intl
                  - messagesDir: ./tmp/strings/
                    enforceDescriptions: true
    custom-transform:
        plugin: ./transforms/custom.js
    envify-dev:
        options:
            NODE_ENV: development
    envify-prod:
        options:
            NODE_ENV: production
    minify:
        plugin: mendel-uglify-js
    coverage:
        plugin: mendel-istanbul
    post-css:
        plugin: mendel-post-css
        options:
            foo: bar # auto-prefixex, rtl-css

types:
    css:
        transforms:
            - post-css
        outlet:
            plugin: mendel-css-pack
    javascript:
        outlet:
            plugin: mendel-bundle-browser-pack
        transforms:
            - envify-dev
            - babelify-dev
        extensions:
            - .js
            - .json
            - .jsx
    node_modules:
        transforms:
            - envify-dev

env:
    production:
        types:
            javascript:
                outlet:
                    plugin: mendel-bundle-rollup
                transforms:
                    - envify-prod
                    - babelify-dev
                    - minify
                node_modules:
                    - envify-prod
                    - minify
    unit-test:
        types:
            javascript:
                transforms:
                    - envify-dev
                    - babelify-dev
                    - coverage

# Order is relevant. E.g.,
# if extract-bundles comes first, we can generate lazy bundle specific css
# if css comes first, css file includes rules from files on lazy bundles
# if node-modules is last, we can use lazy-bundle as optional input (see below)
generators: # AKA graph transforms - or graph operations
    - id: extract-bundles
      plugin: mendel-extract-bundles
    - id: node-modules-generator
      plugin: mendel-extract-node-modules

# "outfile" is optional and only needed for single layer generation
bundles:
    main:
        outfile: app.js
        entries:
            - /apps/main
    lazy-group-1:
        outfile: lazy1.js
        generator: extract-bundles
        from: main
        extract-entries:
            - /apps/lazy
    deps:
        outfile: vendor.js
        generator: node-modules-generator
        all-bundles:
            true # expects only 1 bundle to apply this generator, or throws
            # look for node_modules in every other bundle
        # alternative configuration
        # if the array don't contain lazy, the node_modules only used on lazy would
        # be kept on lazy_bundle
        # bundles:
        #   - mail_app
        #   - compose_app
    css:
        outfile: app.css
        generator: atomic-css-generator
        entries:
            - /apps/main