@gik/npm

    0.1.17 • Public • Published

    @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/npm
    Setup

    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

    ▲ Top


    Scripts

    The tasks available to run against your project.

    To do
    • Add typedef for error codes and Observables.
    Members

    ▲ Top


    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.

    ▲ 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 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.

    ▲ 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.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"
    }

    ▲ 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]
    Related
    Returns

    gik.Types.Observable - An observable which gik 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.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
        }
    }

    ▲ 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
    [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"
        }
    }

    ▲ 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


    Install

    npm i @gik/npm

    DownloadsWeekly Downloads

    120

    Version

    0.1.17

    License

    MIT

    Unpacked Size

    200 kB

    Total Files

    37

    Last publish

    Collaborators

    • etor