@gik/npm 0.1.10

Scripts for your EcmaScript workflow.

Contributors

Héctor Menéndez

Supported platforms

linux
darwin

gik-npm Centralizes and automates the managment of projects based on EcmaScript.
- Scripts The tasks available to run against your project.
  - build Transpiles the current project using babel.
  - docs Generates documentation using js-to-markdown.
  - lint Validates the code complies with certain rules.
  - start A watcher for your scripts using nodemon.
  - test Runs unit tests using Jest.
  - version Automates the versioning of your project using semver.
- Configuration The default settings that control the behaviour of the scripts.

gik-npm

Centralizes and automates the managment of projects based on EcmaScript.

create-react-app inspired us to build this tool, it made our life way easier and so we decided to apply the same principle to our workflow: A single place where to put all the configurationi and automation for our projects in EcmaScript (meaning Node, Cycle, Webpack, React, etc.)

Installation

Nothing special, just like every other tool in your arsenal, install as development dependency and you're good to go.

npm install --save-dev @gik/npm

Setup

Just add a reference to the "binary" gik-npm and pass the needed arguments according to the task you wish to execute.

Parameters

`script`	string	One of the Scripts available.
`[…param]`	string	Each script has it own set of optional arguments, check their section for more information.

Example `package.json`

{
    "scripts": {
        "build": "gik-npm build",
        "ver": "gik-npm version patch",
    }
}

▲ Top

Scripts

The tasks available to run against your project.

To do

Add typedef for error codes and Observables.

Members

build
docs
lint
start
test
version

▲ Top

build

Transpiles the current project using babel.

Base (.babelrc)`

{
    "presets": [
        ["env", {
            "targets": {
                "node": "6.11"
            },
            "modules": "commonjs",
            "useBuiltIns": "usage",
            "loose": false
        }],
        "stage-2"
    ],
    "plugins": [
        "dynamic-import-node"
    ]
}

The following package.json properties are available to you in case you wish to modify the default behaviour.

Properties

`babel`	Object	Options for the babel transpiler.
`[babel.babelrc]`	boolean	Read .babelrc found in context? Default `true`
`[babel.comments]`	boolean	Include comments?
`[babel.compact]`	boolean	Remove unneeded spaces?
`[babel.minified]`	boolean	Minify the number of characters? Default `true`
`[babel.sourceMaps]`	boolean	Wether to include sourcemaps or not. `true` would output the sourcemap as external file. `false` omits it, and `"inline"` puts the contents of the sourcemaps on the same file as the code. Default `inline`
`[babel.extends]`	string	The base .babelrc to extend from. The base file is shown below. but your can specify your own path. Remember that if you put a file on your own folder, it would be taked into account. granted the `babel.babelrc` property is set to `true`.

Returns

gik-npm.Types.Observable - An observable which gik-npm will subscribe to in order to execute it.

▲ Top

docs

Generates documentation using js-to-markdown. The template used for the documentation is customised, you can see how it looks here, since this very documentation was generated by it. This is why even though this script uses js-to-markdown several of their configuration propertes are not available due to the heavy customisation it was done to its original template. Howevet the followin ARE avaialble.

Default `jsdoc.json` config

{
    "sourceType": "module",
    "recurseDepth": 10,
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "plugins": [
        "node_modules/jsdoc-babel"
    ]
}

Properties

`jsdoc`	Object	Options for the documentation generator.
`[jsdoc.template]`	string	The location of documentation template. Default `./template/README.md`
`[private]`	boolean	Wether to show private members or not.
`[configure]`	string	An example of the base configuration is shown below. Default `root/.jsdocrc`

Returns

gik-npm.Types.Observable - An observable which gik-npm will subscribe to in order to execute it.

To do

Add documentation about how to customize the template and the available helpers.

▲ Top

lint

Validates the code complies with certain rules. It's recommended that you install one of the flavours of eslint-config to accompany this script. it will be as easy as to include an .eslintrc file extending the module.

Parameters

[target] string | Array The target directory to lint. Default src

Returns

gik-npm.Types.Observable - An observable which gik-npm will subscribe to in order to execute it.

Example `package.json`

{
    "directories": {
        "example": './example'
    },
    "scripts": {
        "lint": "gik-npm lint example"
    },
    "devDependencies": {
         "@gik/eslint-config-node": "x.x.x" // Pick a flavour according to your project
    }
}

Example `.eslintrc`

{
    "extends": "@gik/node" // Same as the module but without "eslint-config"
}

▲ Top

start

A watcher for your scripts using nodemon.

Below are the default properties that are being sent to the nodemon binary.

Parameters

exec string The command to run whenever changes are found.

Properties

`[verbose]`	boolean	Show details of what's happening. Default `true`
`[ext]`	string	The extensions that triggers changes. Default `js json`
`[watch]`	Array	The directories to monitor. Default `[...$npm_package_directories]`

https://github.com/remy/nodemon#config-files

Returns

gik-npm.Types.Observable - An observable which gik-npm will subscribe to in order to execute it.

▲ Top

test

Runs unit tests using Jest. This script makes no assumptions for the jest configurations, it just transpiles the test files using the same configuration as the build script and uses Jest's defaults. Below is the configuration file used by the script.

Default configuration `.jest.js`

const PATH = require('path');

module.exports = {
    verbose: true,
    bail: true,
    collectCoverage: true,
    testMatch: ['**/__tests__/**/*.js?(x)'], // only files inside the __tests__ folder
    transform: {
        '^.+\\.jsx?$': PATH.join(__dirname, 'lib', 'test-transform'),
    },
};

you can customize the arguments sent to the jest cli interface by changing the following properties on package.json.

Properties

`[projects]`	Array	The projects to test. Default `path/to/your/project`
`[rootDir]`	string	Just will run on this context. Default `path/to/your/project`
`[config]`	string	Use this file to customize further. Default `path/to/default/config`

Returns

gik-npm.Types.Observable - An observable which gik-npm will subscribe to in order to execute it.

Example `package.json`

{
    "@gik/npm": {
         "jest": {
              "config": "path/to/your/config",
         }
     }
    "scripts": {
        "test": "gik-npm test", // runs test on all files on "./test"
        "test:cover": "gik-npm test cover", // runs test and generates coverage report
    }
}

▲ Top

version

Automates the versioning of your project using semver. internally uses npm version (avoiding tagging) and after modifying package.json adds it to git. This is specially useful if you add it to a precommit script (already available when using this library via husky), making the change available on that commit automatically.

Available semver types:

major 0.0.0 -> 1.0.0
minor 0.0.0 -> 0.1.0
patch 0.0.0 -> 0.0.1
prerelease
- 0.0.0 -> 0.0.0-1
- 0.0.0-beta -> v0.0.0-beta.0
- 0.0.0-beta.0 -> 0.0.0-beta.1

Parameters

[type] string One of the valid semver version names. Default patch

Returns

gik-npm.Types.Observable - An observable which gik-npm will subscribe to in order to execute it.

Example `packge.json`

{
    "scripts": {
        // builds, bumps package.json and generartes docs using the new version
        "precommit": "gik-npm build && gik-npm version patch && git-npm docs"
    }
}

▲ Top

Configuration

The default settings that control the behaviour of the scripts.

Properties

`directories`	Object	Lets NPM know where are some directories. This has the added benefit of letting you use this assign environment variables Either on your project or in their scripts object.
`[directories.src]`	string	The path for the source files. Default `./src`
`[directories.out]`	string	The path for the transpiled files. Default `./lib`
`[directories.template]`	string	The path for the template files. Default `./template`
`@gik/npm`	Object	The container for the script-specific options. Check their section for more information.

Example `package.json`

{
    "directories": {
         "src": "./src",
         "out": "./lib"
     },
    "scripts": {
         "example": "your-script $npm_package_directories_src"
     },
    "@gik/npm": {
        "doc": "./README.md"
    },
}

▲ Top

cgarstin/npm

@gik/npm 0.1.10

Contributors

Supported platforms

Table of contents

gik-npm

Installation

Setup

Parameters

Example package.json

Members

Scripts

To do

Members

build

Base (.babelrc)`

Properties

Returns

docs

Default jsdoc.json config

Properties

Returns

To do

lint

Parameters

Returns

Example package.json

Example .eslintrc

start

Parameters

Properties

Related

Returns

test

Default configuration .jest.js

Properties

Returns

Example package.json

version

Available semver types:

Parameters

Returns

Example packge.json

Configuration

Properties

Example package.json

Example `package.json`

Default `jsdoc.json` config

Example `package.json`

Example `.eslintrc`

Default configuration `.jest.js`

Example `package.json`

Example `packge.json`

Example `package.json`