@skeate/mimosa-defeature

mimosa-defeature

A mimosa module for flagging features and removing them from a project build. This is an external module and does not come by default with Mimosa.

For more information regarding mimosa, see http://mimosa.io

Usage

Add 'defeature' to your list of modules. Mimosa will install the module for you on start up. For a detailed example of how to use this module, refer to this sample project.

Flagging features

You can flag javascript, css, and template code as features. In general, you can flag a feature by creating a block comment in your source file that follows the following format:

<blank space>feature featureName[:optionalFlag]<blank space>

• featureName is the name of your feature.
• When no optionalFlag is used, defeature will flag the next line as a part of your feature.
• optionalFlag can be one of the following values:
  • start Signals the start of a feature code block
  • end Signals the end of a feature code block
  • file Signals that the entire file is part of a feature

CSS

The defeature module will allow you to defeature plain CSS files as well as SASS files. You will also be able to use defeature with other CSS preprocessors as long as the @import behaviour for partials is similar to SASS. One important thing to note when using CSS preprocessors is that the :file optional flag will not work as expected so it's best to avoid it. Additionally, when using CSS preprocessors, using a feature comment with no optional flags above an '@import' line will not work as expected, as it will NOT feature flag the entire partial being imported, but instead it will feature flag the first line of the partial.

Note: The defeature module will replace unwanted feature flagged CSS code with empty space (new line characters equaling in number to the lines in the original code). This is done in order for source maps to work as expected when using CSS preprocessors.

Examples:

/* feature my_feature:start */
@import 'components/search_status_popover';
/* feature my_feature:end */

// Will feature flag the entire partial

/* feature my_feature */
@import 'components/search_status_popover';

// Will feature flag the first line of the partial

/* feature tags:start */
.icon-tag {
  color: red;
  display: inline-block;
}
/* feature tags:end */

// Will feature flag a block of css

.icon-tag {
  color: red;
  /* feature tags */
  display: inline-block;
}

// Will feature flag a line of css

Javascript

defeature allows you to feature flag javascript files.

Examples:

/* feature my_feature:file */
var hello;
...
...
...

// Will feature flag entire file

/* feature my_feature */
var hello;
var foo = 3;

// Will feature flag 'var hello;'

/* feature my_feature:start */
var hello;
var foo = 3;
/* feature my_feature:end */

// Will feature flag block of javascript

Templates

defeature currently only allows you to feature flag Handlebars templates.

Examples:

{{!-- feature download-documents:file --}}
<div class="download-modal">
  <div class="title">Download Documents</div>
  ...
  ...
  ...

// Will feature flag entire template file

<div class="download-modal">
  <div class="title">Download Documents</div>
  {{!-- feature download-documents --}}
  <span class="foo">hello</span>
</div>


// Will feature flag the next line

<div class="download-modal">
  {{!-- feature download-documents:start --}}
  <div class="title">Download Documents</div>
  <span class="foo">hello</span>
  {{!-- feature download-documents:end --}}
</div>


// Will feature flag a template block

Removing features

Then inclusion or exclusion of features depends on the values present in your master and child files, which you can specify in the module config. Nested features will result in hyphenated feature names.

Examples

Master file

{
  "my_feature": false,
  "foo": {
    "geo": {
      "heatmap": true,
      "overlay": false
    }
  }
}


The following features will be excluded from the build: 'my_feature', 'foo-geo-overlay'

Master file

{
  "my_feature": true,
  "foo": {
    "geo": {
      "heatmap": true,
      "overlay": true
    }
  }
}

Child file

{
  "foo": false
}


The following features will be excluded from the build: 'foo-geo-overlay', 'foo-geo-heatmap

Functionality

The defeature module will remove flagged features from your source code. The module will use master and child files to determine which features to remove. These files should be in json format. The module will look for these files in the folder that you specify in the config. You should specify a child file if different versions of your application will have different features. Usually, you'll have one child file per version of your app. You can use mimosa profiles to switch between versions.

If both master and child are present, defeature will perform a smart merge of the two files to determine the final feature list. If only master is present, it will use the values in master to determine the final feature list. You can nest features in both master and child files.

mimosa will remove features when your run mimosa watch or mimosa build.

build v watch exclusion

A feature called mimosa-build-exclude is automatically recognized by mimosa-defeature. This included feature allows for excluding features based on whether Mimosa is running a watch or a build. When running a build, all code using the mimosa-build-exclude feature flag will be removed/commented.

NODE_ENV=production

An environment-production feature is automatically included if NODE_ENV is set to production. Otherwise the environment-production feature is automatically excluded.

Default Config

defeature: {
  folder: "feature",
  features: {
    master: "master",
    child: null
  },
  removeFileDefeatures: {
    template: true,
    javascript: true
  }
}

removeFileDefeatures object

An object indicating when the defeaturing of a file should result in that file being excluded from output.

removeFileDefeatures.template boolean

A flag, when set to true (which is the default), will result in the template file being excluded from template processing, which means it will not be merged together by any of Mimosa's template compilers. If set to false, defeature will retain file excluded templates, and those templates will be used by Mimosa's template compilers as contentless.

removeFileDefeatures.javascript boolean

A flag, when set to true (which is the default), will result in the javascript file not being processed any further.

Example Config

defeature: {
  folder: "feature",
  features: {
    master: "master",
    child: "admin"
  }
}