yoshi

A tool for common tasks in Javascript projects.

Features

• Transpile to ES6/Typescript
• Support React/Angular 1.x (2.0 will be supported soon)
• Browser tests using protractor / Selenium Webdriver
• Unit tests using Jest/Mocha/karma
• ESlint/TSlint
• CSS Modules
• Sass
• Local dev environment running node server / cdn server
• Wallaby
• async/await (babel-polyfill needed)
• Minify/Uglify
• Bundle JS/CSS using Webpack
• External/Inline css
• Webpack 2 (tree shaking)

Install

npm install --save-dev yoshi

Sample usage

In your package.json:

{
  "scripts": {
    "start": "yoshi start",
    "test": "yoshi test",
    "build": "yoshi lint && yoshi build",
    "release": "yoshi release" //only needed if you publish to npm
    ...
  }
}

Or within the command-line:

yoshi [command] [options]

---

CLI

The following sections describe the available tasks in yoshi. You can always use the --help flag for every task to see its usage.

start

Flag	Short Flag	Description	Default Value
--entry-point	-e	Entry point for the app.	./dist/index.js
--watch	-w	Watches project files, rebuilds and restarts on change.	false

This will run the specified (server) entryPoint file and mount a CDN server.

The following are the default values for the CDN server's port and the mount directory. You can change them in your package.json:

"yoshi": {
  "servers": {
    "cdn": {
      "port": 3200,
      "dir": "dist/statics"
    }
  }
}

build

Flag	Short Flag	Description	Default Value
--output		The output directory for static assets.	statics
--context		The directory used for resolving entries. More info here.	src

This task will perform the following:

1. Compile using TypeScript (*.ts) or babel (*.js) files into dist/. In case you do not want to transpile server (node), you can remove .babelrc/tsconfig/package json's babel key. If you still need those (for transpiling client code), please use yoshi.runIndividualTranspiler.
2. Copy assets to dist folder (ejs/html/images...).
3. Bundle the entry points using Webpack and compile sass files when --bundle flag is on.

You can specify multiple entry points in your package.json file. This gives the ability build multiple bundles at once. More info about Webpack entries can be found here.

"yoshi": {
  "entry": {
    "a": "./a",
    "b": "./b",
    "c": ["./c", "./d"]
  }
}

Note: the decision whether to use TypeScript or babel is done by searching tsconfig.json inside the root directory.

test

Flag	Description
--mocha	Run unit tests with Mocha - this is the default
--jasmine	Run unit tests with Jasmine
--karma	Run tests with Karma (browser)
--jest	Run tests with Jest
--protractor	Run e2e tests with Protractor (e2e)

By default, this task executes both unit test (using mocha as default) and e2e test using protractor. Default unit test glob is {test,app,src}/**/*.spec.+(js|ts). You can change this by adding the following to your package.json:

yoshi: {
  specs: {
    node: 'my-crazy-tests-glob-here'
  }
}

• Note that when specifying multiple flags, only the first one will be considered, so you can't compose test runners (for now).

• Mocha tests setup:

  You can add a test/mocha-setup.js file, with mocha tests specific setup. Mocha will require this file, if exists. Example for such test/mocha-setup.js:

  import 'babel-polyfill';
  import 'isomorphic-fetch';
  import sinonChai from 'sinon-chai';
  import chaiAsPromised from 'chai-as-promised';
  import chai from 'chai';
  
  chai.use(sinonChai);
  chai.use(chaiAsPromised);

• Karma tests setup:

  When running tests using Karma, make sure you have the right configurations in your package.json as described in yoshi.specs section. In addition, if you have a karma.conf.js file, the configurations will be merged with our built-in configurations.

lint

Flag	Short Flag	Description
--client	-c	Runs linters for client only (stylelint).

Executes TSLint or ESLint (depending on the type of the project) over all matched files. An '.eslintrc' / tslint.json file with proper configurations is required.

release

Bump package.json version and publish to npm using wnpm-release.

---

Configurations

Configurations are meant to be inside package.json under yoshi section or by passing flags to common tasks.

Flags

See above sections.

Configurations in package.json

yoshi.separateCss

By default, your required css will bundled to a separate app.css bundle. You can leave your css in main js bundle by adding the following to your package.json:

"yoshi": {
  "separateCss": false
}

yoshi.cssModules

We use css modules as default. You can disable this option any time by adding the following to wix section inside your package.json:

"yoshi": {
  "cssModules": false
}

Using css modules inside your component is easy:

import s from './Counter.scss';//import css/scss

<p className={s.mainColor}>{counterValue}</p>

Using css when css modules are turned off:

import s from './Counter.scss';//import css/scss

<p className="mainColor">{counterValue}</p>

yoshi.entry

Explanation is in cli/build section.

yoshi.servers.cdn

Explanation is in cli/start section.

yoshi.specs

Specs globs are configurable. browser is for karma, node is for mocha and jasmine.

{
  "yoshi": {
    "specs": {
      "browser": "dist/custom/globs/**/*.spec.js",
      "node": "dist/custom/globs/**/*.spec.js"
    }
  }
}

For example:

{
  "yoshi": {
    "specs": {
      "browser": "dist/src/client/**/*.spec.js",
      "node": "dist/src/server/**/*.spec.js"
    }
  }
}

yoshi.runIndividualTranspiler

In case you don't want to transpile your server (node) code, and you still need .babelrc/tsconfig, you can add runIndividualTranspiler flag to skip server transpiling.

yoshi.externalUnprocessedModules

You can explicitly ask build process to transpile some node modules in case those modules do not contain transpiled code. Note that this is not a recommended workflow. It can be very error prone:

1. It might be for example that your app babel config and the node module babel config will be conflicting.
2. Any babel plugin that is used by your dependencies will need to be installed by your app as well.
3. You'll need to also add nested dependencies that need transpiling into array, which can be confusing.

Anyway, if you don't have a better alternative you can pass array with module names in this property.

yoshi.exports

If set, export the bundle as library. yoshi.exports is the name.

Use this if you are writing a library and want to publish it as single file. Library will be exported with UMD format.

##FAQ

• How do I debug my application/tests?
• How to add external assets to my client part of the project?
• How do I setup Enzyme test environment?
• How to disable css modules in specific places
• How to I analyze my webpack bundle contents