node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

shared-grunt-config

shared-grunt-config

Table Of Contents

# Description

This repository exposes grunt configuration that can be shared between multiple modules.

# Usage

npm install --save-dev grunt shared-grunt-config
 
# These tasks come preconfigured with shared-grunt-config. You need to install
# them as dependencies of your own repo.
npm install --save-dev @retailmenot/grunt-hooks \
grunt-contrib-clean \
grunt-contrib-watch \
grunt-eslint \
grunt-jsdoc \
grunt-jsinspect \
grunt-release \
grunt-todo

## Gruntfile.js

module.exports = function( grunt ) {
    require( 'shared-grunt-config' )( grunt, {
        alsoLoadFrom: false
    } );
};

alsoLoadFrom can be a directory within your repo. The directory will be loaded with load-grunt-config and merged with the final grunt config object.

TODO In the future, an error will be thrown if the config in alsoLoadFrom collides with the config already provided by this repository. (see #7)[https://github.com/lzilioli/shared-grunt-config/issues/7]

## Recommendation

If you use this repo, you will want the following in your .gitingore and .npmignore files.

### .gitignore

.DS_Store
node_modules/
npm-debug.log*
 
*.ignore
docs/
*.log

### .npmignore

*.ignore
!docs/
Gruntfile.js
# if you use the alsoLoad from option
config/grunt/

## API

The object returned by invoking the method exported by shared-grunt-config exposes an API for modifying certain parts of the configuration for the consuming repo.

Each method is chain-able, and is explained below:

module.exports = function( grunt ) {
    require( 'shared-grunt-config' )( grunt )
 
    // add more files in which to search for TODOs 
    // during the grunt TODO task 
    .addTodo([ 'bin/*.sh' ])
 
    // add files for js stuff like linting, beautifying, etc. 
    // will also be used for the todo and jsdoc task 
    .addJs([ 'client/**/*.js' ])
 
    // Add files to be cleaned by grunt clean 
    .addClean([ 'client-dist/' ]);
};

# Tasks

## Watch Tasks

### default

The default task is run when typing grunt. When a file being watched changes, the following will happen:

  • the source will be modified and linted by the jsb task
  • jsdocs will be generated to docs.ignore within your repository

### o-* tasks

There are two "optimized" tasks defined:

  • o-lint
  • o-docs

These are very similar to the default task, however they are optimized to focus on one of the two things. e.g. the o-docs task will watch only files relevant to generating jsdoc, and will quickly generate jsdoc when files change so you can quickly refresh your browser to see how the docs have changed.

## hooks

Running this task will install two git hooks in your repo's ./.git/hooks/ directory: pre-push, and post-commit.

## release:version|major|minor|patch

Perform a release of the module using grunt-release.

Before doing so, this task generatesjsdoc to docs/ rather than docs.ignore/. With the recommended .gitignore and .npmignore settings, this distinction does not matter. It will be removed in #5.

You should add a prepublish npm hook that runs grunt jsdoc.

"scripts": {
    "quality": "grunt audit lint",
    "prepublish": "npm run quality && grunt clean build && grunt jsdoc:dist"
}

Your CHANGELOG.md will be updated to include a header at the top of the file with the release version and date. This lets you keep a running list of feature changes as you work, and not have to worry about remembering to associate the changes with a release in the CHANGELOG.

# Other Tasks

### audit

The audit task will review your code and tell you how it went. It will check for TODOs, and try to detect duplicate JS to aid in DRYing out your code.

### lint

Alias for eslint with fix: false. This will not modify your code, but will fail if it is not up to par.

### jsb

Alias for eslint with fix: true. This will change the code to match the coding standards.

### clean

This task will clean files that get automatically generated by the grunt setup exposed by this repo. You can add more files to clean with the addClean method.

### jsdoc

Generate documentation for the current repo.

This task has two targets :dev and :dist. dev will generate documentation in a directory named docs.ignore, and dist will generate the documentation in a directory named docs.

To view non-fatal warnings encountered by jsdoc during doc generation, run your grunt task with the flag --w-jsd.