@gik/npm 0.1.17
Scripts for your ECMAScript workflow.
Contributors
Supported platforms
- linux
- darwin
Table of contents
- gik Centralizes and automates the management 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
Centralizes and automates the management 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 configuration 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/npmSetup
Just add a reference to the "binary" gik 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 build",
"ver": "gik version patch",
}
}Members
Scripts
The tasks available to run against your project.
To do
- [ ] Add typedef for error codes and Observables.
Members
build
Transpiles the current project using babel.
Base (.babelrc)`
{
"presets": [
[
"@babel/env",
{
"targets": {
"node": "current"
},
"modules": "commonjs",
"useBuiltIns": false,
"loose": false
}
]
],
"plugins": [
// STAGE-2
"@babel/plugin-proposal-class-properties",
[
"@babel/plugin-proposal-decorators",
{
"legacy": true
}
],
"@babel/plugin-proposal-export-namespace-from",
"@babel/plugin-proposal-function-sent",
"@babel/plugin-proposal-json-strings",
"@babel/plugin-proposal-numeric-separator",
"@babel/plugin-proposal-throw-expressions",
"@babel/plugin-syntax-dynamic-import",
"@babel/plugin-syntax-import-meta"
]
}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 | Whether 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.Types.Observable - An observable which gik will subscribe to
in order to execute it.
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 properties are not available due to the heavy customisation it was done to its original template. However the following ARE available.
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 | Whether to show private members or not. |
[configure]
|
string | An example of the base configuration is
shown below. Default root/.jsdocrc
|
Returns
gik.Types.Observable - An observable which gik will subscribe to
in order to execute it.
To do
- [ ] Add documentation about how to customize the template and the available helpers.
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.Types.Observable - An observable which gik will subscribe to
in order to execute it.
Example package.json
{
"directories": {
"example": './example'
},
"scripts": {
"lint": "gik 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"
}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]
|
Related
Returns
gik.Types.Observable - An observable which gik will subscribe to
in order to execute it.
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.Types.Observable - An observable which gik will subscribe to
in order to execute it.
Example package.json
{
"@gik/npm": {
"jest": {
"config": "path/to/your/config",
}
}
"scripts": {
"test": "gik test", // runs test on all files on "./test"
"test:cover": "gik test cover", // runs test and generates coverage report
}
}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-10.0.0-beta -> v0.0.0-beta.00.0.0-beta.0 -> 0.0.0-beta.1
Parameters
[type]
|
string | One of the valid semver version names. Default patch
|
[extra]
|
string | Extra options. currently only "--no-add" available. |
Returns
gik.Types.Observable - An observable which gik 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 build && gik version patch && git-npm docs"
}
}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"
},
}