kf-spinjs v0.1.1

spinjs - the best build tool - is the one that don't need build rules

Installation

npm install -g spinjs

Motivation

spinjs was created to free the developer from build rules writing for JavaScript projects as much as possible. Its difference from many other build tools with similair goals is that spinjs is not tied to specific framework and does not attempt to lock you out from generated config. spinjs does its best to provide you with very mature build setup from the minimal information provided by you about your tech stack and lets you further customize every aspect of build setup when needed.

Basic Usage

The basic spinjs usage is simple: you describe the stack used in your application in the property spin of package.json:

{
  "spin": "webpack:babel:apollo:react-native:ios"
}

and you are all set.

You can then execute

spin watch

to launch your project in webpack watch mode for development. After making changes to your code, they will be automatically reloaded from disk using Webpack Hot Module Replacement.

spin build

will build your project for production environment.

spin test "src/**/*.spec.js"

will run tests located in .spec.js files via Mocha Webpack.

To see generated Webpack config add -v option to any of the above commands, e.g.:

spin -v watch

will launch project in development mode and will dump generated Webpack config in a terminal.

Supported technologies stack

At the moment spinjs supports the following technologies, that can be specified inside stack property:

Concepts

spinjs configures and launches multiple builders in parallel to build the project. If stack for the project is specified in spin property of package.json, then only one builder is launched. To specify multiple builders the following configuration should be used:

{
    "spin": {
        "builders": {
            "backend": {
                "stack": "webpack:babel:apollo:react:styled-components:sass:server"
            },
            "frontend": {
                "stack": "webpack:babel:apollo:react:styled-components:sass:web"
            },
            "mobile": {
                "stack": "webpack:babel:apollo:react-native:styled-components:sass:ios"
            }
        }
    }
}

The 'spinjs' configuration can be specified in .spinrc.json instead of package.json, it should contain the value of spin property in this case. The object with config can be also exported from .spinrc.js

Each builder has a name and a stack property at minimum. Builder properties recognized by spinjs:

Common builder options can be put into options property, from there they will be copied into each builder. stack property inside options will be prepended to each builder stack. Builder can also have builder-specific options, depending on its stack, recognized by spinjs plugins.

Each spinjs plugin tries to handle subset of technologies in the builder stack to configure build tools usually used for this stack the best way. After configuration of the builder it gets executed in the mode that specified in spin command line, i.e. watch, build, test, etc.

There are several built-in plugins supplied with spinjs. External plugins can be specified inside options -> plugins property.

Webpack, Babel and other tool-specific config merging

spinjs generates configs for various tools based on the stack specified, but sometimes you want to tweak generated configs. For this purpose you can provide webpackConfig, babelConfig, etc keys to each builder or into options if you want tweaking happen for each builder in config.

The values provided in these keys will be merged with config generated by spinjs with webpack-merge. You should check the result of this merging by running spinjs with -v option to show resulting configs, example: npx spin -v watch

Though webpack-merge uses smart strategy to merge generated configs and the configs provided by you, but it is not smart enough in many cases and you need to configure merge strategy too, to get desirable results. For this purpose you should specify merge field inside webpackConfig, babelConfig etc, with strategy used by webpack-merge. Example:

const config = {
  ...,
  options: {
    babelConfig:
    {
       merge: { presets: 'replace' },
       presets: [
         ["babel-preset-env", {modules: 'commonjs'}],
         "react",
         "stage-0"
       ],
    }
  }
}

See webpack-merge strategies documentation here

Current working directory

When reading .spinrc.js configs spinjs does so recursively in all the child directories. When config in each such directory is being read or builder get executed, process current working directory is set to point to this same directory. This scheme of operation should be compatible to all 3rd party tools.

Profiling builders

To troubleshoot builder performance set profile: true option on the builder. This will generate profileEvents.json file inside build dir. In order to view the profile file:

• Go to Chrome, open DevTools, and go to the Performance tab (formerly Timeline).
• Drag and drop generated file profileEvents.json into the profiler.

It will then display timeline stats and calls info.

Community support

• Gitter channel - questions, answers, general discussions
• GitHub issues - submit issues, send feature requests

Commercial support

SysGears team provides advanced support for commercial partners. A commercial partner will have a premium access to our team whether this is to help you with your code based on this project or related technologies used in it. Contact us using Skype or via email: info@sysgears.com

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

License

Copyright © 2017 SysGears INC. This source code is licensed under the MIT license.