moe-scripts

• Description
• Synopsis
• Beware
• Problem
• Solution
• Configuration
  • Overriding Configuration
    • ESLint
    • TSLint
    • Babel
    • Jest
• Inspiration
• API
  • Modules
  • build
  • commit
  • contributors
  • doc
  • format
  • info
  • init
  • lint
  • precommit
  • reset
  • test
  • travis-after-success
  • validate

Description

CLI toolbox for common scripts for JavaScript / TypeScript projects. Inspired by "Tools without config" and kcd-scripts

Synopsis

1. Create a project:
   • npm init my-project
   • If TypeScript: add types into package.json such as:
     • { "types": "lib/index" }
2. Install:
   • npm install --save-dev moe-scripts
3. Use scripts:
   • npm run build -- --watch
   • npm run build:doc
   • npm run validate
   • npm run commit
   • npm run release
   • ... etc.

Beware

Build yours using script-helper.

Instead of using this toolbox directly, consider creating yours using script-helper. This library is an example usage for script-helper and not meant for general use.

If it fits you, fork it, because it may change from version to version according to needs of author.

Problem

There are lots of configuration and boilerplate to start and maintain a JavaScript project. It is very tiresome to update libraries and configurations within multiple projects. See "Tools without config"

Solution

This toolkit is provided as an npm module and every configuration for linting, testing, building and more are initialized with a single command and updated simply updating a single npm package.

Configuration

This toolkit exposes a bin called moe-scripts. All scripts are stored in lib/scripts and all configurations are stored either in lib/config or in root of the library.

Toolkit decide whether a project is a TypeScript project or JavaScript project by looking types entry in package.json.

moe-scripts init is automatically executed after package install and creates configuration files and entries in package.json if they do not exist. See init script below.

All scripts can be further refined used arguments related to used tool within that script. It is mostly avoided to provide extra besides original ones of the tool parameters if really not necessary.

Overriding Configuration

Most of the configuration can be extended by native extend mechanism of the related library. Those which cannot be extended such as .gitignore or can be extended but behaves according to location of extended file such as tsconfig.json are used with symbolic links pointing to a file in this toolkit.

All of the configuration can be overridden.

This can be a very helpful way to make editor integration work for tools like ESLint which require project-based ESLint configuration to be present to work.

ESLint

Create an .eslintrc with the contents of:

{"extends": "./node_modules/moe-scripts/eslint.js"}

Note: for now, you'll have to include an .eslintignore in your project until this eslint issue is resolved.

TSLint

It is extendible via:

{ "extends": "moe-scripts/tslint.json" }

Note: tslint.json is not a symbolic link in source root. There is no safe place to link it, because lib is not always available in source and src is not available in npm package.

Babel

Or, for babel, a .babelrc with:

{"presets": ["moe-scripts/babel"]}

Jest

const {jest: jestConfig} = require('moe-scripts/config')
module.exports = Object.assign(jestConfig, {
  // your overrides here
 
  // for test written in Typescript, add:
  transform: {
    '\\.(ts|tsx)$': '<rootDir>/node_modules/ts-jest/preprocessor.js',
  },
})

Inspiration

This toolkit is based on and very heavily inspired by kcd-scripts. I'm also grateful for his Tools without config article. I created this as a fork and a separate toolkit instead of contributing it, because he mentioned that, like me, kcd-scripts are a personal project and specific to his needs. (Like this one is specific to my needs).

API

Modules

build

Build project using TypeScript, Babel or rollup based on project type.

TypeScript

• Copies js and d.ts files from src to lib using rsync, because tsc does not allow --allowJs and --declaration parameters at the same time.
• Cleans target directory before build.

Babel

• If no --ignore parameter presents, ignores by default: tests, mocks, test_supplements, test_helpers, *.(test|spec).(js|ts|jsx|tsx)

commit

Starts commitizen interactive CLI to commit staged files adhering conventional-changelog using cz-conventional-changelog plugin.

contributors

WIP

doc

Generates documentation.

• Creates or updates README.md file from README.hbs handlebars template file and JSDoc comments in source files.
• Generates table of contents.
• If no --configure parameter is present and no configuration file is available, uses builtin configuration provided by this library.
• If no --files parameter given, uses all files recursively in src directory.
• If no --template parameter given, uses README.hbs` in project root.

format

Formats project using prettier.

• If no config provided (--config, prettier.config.js or prettierrc in package.json) uses builtin configuration provided by this library.
• If no --ignore-path parameter provided or no .prettierignore file is present uses builtin ignore file provided by this library.

info

Displays information about project and this module.

init

Initializes project

init script generates necessary files and updates package.json. This script executed automatically during install at preinstall and postinstall stages. Also can be manually executed. In addition modification can be reversed using reset script.

Adds necessary entries in package.json and creates files.

Entries in package.json

Entry	Description
main	Primary entry point to your program
files	Files to publish in npm package
scripts.file	Watch and execute a file when it changes
scripts.watch	Watch amd build project when files change
scripts.build	Build project
scripts.build:doc	Build README.md from handlebars template and JSDoc comments
scripts.test	Test project using Jest
scripts.test:update	Test project using Jest and updating snapshots
scripts.lint	Lint project
scripts.format	Format project
scripts.validate	Execute validation scripts
scripts.commit	Commit project
scripts.prepublishOnly	Build project before publishing to npm
scripts.squash	Sqush and merge project branch
scripts.release	Publish project to git and npm repo

Files

File	Track	Link	Description
.git/hooks			(Only during preinstall) githooks directory
.env	✓		Environment variables to read from using dotenv (also included)
.env.sample	✓		Sample file for .env
.npmignore	✓	✓	Npm ignore file provided by this library
.gitignore	✓	✓	Git ignore file provided by this library
.gitattributes	✓	✓	Gitattributes file provided by this library
CHANGELOG.md			A base change log file
.editorconfig	✓		Editor configruation file
LICENSE	✓		License file based on license type in package.json
README.hbs	✓		Readme template in handlebars format
.prettierrc.js	✓		Prettier configuration file
.prettierignore	✓	✓	Ignore file for prettier
.huskyrc.js	✓		husky Configuration file to manage git hooks from npm scripts
commitlint.config.js	✓		commitlint Configuration file to lint commit messages
tslint.json	✓		TSLint configuration file
.eslintrc	✓		ESLint configuration file
tsconfig.json	✓		TypeScript configuration file. (Not created as link, for IDEs
tsconfig-test.json	✓	✓	TypeScript configuration file used during testing

lint

Lints project using TSLint or ESLint

TSLint

• If project has no tslint.json or no --config is given, uses builtin configuration provided by this library.
• If no files and --project argument given, uses default TypeScript project (tsconfig.json located in the root of project).

ESLint

• If project has no ESLint configuration (.eslintrc.js or eslintConfig in package.json etc.) or no --config is given, uses builtin configuration provided by this library.
• If no --ignore-path argument is given uses .gitignore.
• Uses --cache by default. (Can be disabled by --no-cache).

precommit

Script to be executed automatically just before commit. Utilizes lint-staged

This script is defined in .huskyrc.js as required. It is used by husky and contains lint-staged config.

• If no config provided (--config, lint-staged.config.js or lint-staged in package.json) uses builtin configuration provided by this library.
• Builds README.md and adds it to git
• Executes lint-staged.
  • format (If not opted out) and add to git
  • lint
  • test (executes test related to changed files)
• If opted in, executes validation script.

reset

Reverses modifications made by this library. (Please note that deleted files are not reversed. You should recover them from git repo)

test

Test project using Jest

• Sets BABEL_ENV and NODE_ENV to test.
• If not in CI, precommit stage, or following arguments are not present --no-watch, --coverage, --updateSnapshot or --watchAll, watches changes.
• If no config provided (--config, jest.config.js etc.) uses builtin configuration provided by this library.

travis-after-success

WIP

validate

Validates project.

Executes following tasks based on the event being in:

Event	Tasks
precommit	lint, test, flow or typescript, nsp
other	flow or typescript, nsp

To avoid redundant execution, lint and test are not executed in precommit stage because those are executed in precommit script already.

build

Build project using TypeScript, Babel or rollup based on project type.

TypeScript

• Copies js and d.ts files from src to lib using rsync, because tsc does not allow --allowJs and --declaration parameters at the same time.
• Cleans target directory before build.

Babel

• If no --ignore parameter presents, ignores by default: __tests__, __mocks__, __test_supplements__, __test_helpers__, *.(test|spec).(js|ts|jsx|tsx)

Properties

Example

$ npm run build -- --watch --preserveWatchOutput
$ npx moe-scripts build
$ npx moe-scripts build --watch --preserveWatchOutput

commit

Starts commitizen interactive CLI to commit staged files adhering conventional-changelog using cz-conventional-changelog plugin.

Example

$ npm run commit
$ npx moe-scripts commit

contributors

WIP

Example

$ npx moe-scripts contributors

doc

Generates documentation.

• Creates or updates README.md file from README.hbs handlebars template file and JSDoc comments in source files.
• Generates table of contents.
• If no --configure parameter is present and no configuration file is available, uses builtin configuration provided by this library.
• If no --files parameter given, uses all files recursively in src directory.
• If no --template parameter given, uses README.hbs` in project root.

Properties

Example

$ npm run build:doc
$ npx moe-scripts doc

format

Formats project using prettier.

• If no config provided (--config, prettier.config.js or prettierrc in package.json) uses builtin configuration provided by this library.
• If no --ignore-path parameter provided or no .prettierignore file is present uses builtin ignore file provided by this library.

Properties

Example

$ npm run format
$ npx moe-scripts format

info

Displays information about project and this module.

Example

$ npx moe-scripts info

init

Initializes project

init script generates necessary files and updates package.json. This script executed automatically during install at preinstall and postinstall stages. Also can be manually executed. In addition modification can be reversed using reset script.

Adds necessary entries in package.json and creates files.

Entries in package.json

Files

File	Track	Link	Description
.git/hooks			(Only during preinstall) githooks directory
.env	✓		Environment variables to read from using dotenv (also included)
.env.sample	✓		Sample file for .env
.npmignore	✓	✓	Npm ignore file provided by this library
.gitignore	✓	✓	Git ignore file provided by this library
.gitattributes	✓	✓	Gitattributes file provided by this library
CHANGELOG.md			A base change log file
.editorconfig	✓		Editor configruation file
LICENSE	✓		License file based on license type in package.json
README.hbs	✓		Readme template in handlebars format
.prettierrc.js	✓		Prettier configuration file
.prettierignore	✓	✓	Ignore file for prettier
.huskyrc.js	✓		husky Configuration file to manage git hooks from npm scripts
commitlint.config.js	✓		commitlint Configuration file to lint commit messages
tslint.json	✓		TSLint configuration file
.eslintrc	✓		ESLint configuration file
tsconfig.json	✓		TypeScript configuration file. (Not created as link, for IDEs
tsconfig-test.json	✓	✓	TypeScript configuration file used during testing

Properties

Example

$ npx moe-scripts init

lint

Lints project using TSLint or ESLint

TSLint

• If project has no tslint.json or no --config is given, uses builtin configuration provided by this library.
• If no files and --project argument given, uses default TypeScript project (tsconfig.json located in the root of project).

ESLint

• If project has no ESLint configuration (.eslintrc.js or eslintConfig in package.json etc.) or no --config is given, uses builtin configuration provided by this library.
• If no --ignore-path argument is given uses .gitignore.
• Uses --cache by default. (Can be disabled by --no-cache).

Properties

Example

$ npm run lint
$ npm run lint my-file.ts -- --config my-config.json
$ npx moe-scripts lint
$ npx moe-scripts lint --no-cache
$ npx moe-scripts lint my-file.ts

precommit

Script to be executed automatically just before commit. Utilizes lint-staged

This script is defined in .huskyrc.js as required. It is used by husky and contains lint-staged config.

• If no config provided (--config, lint-staged.config.js or lint-staged in package.json) uses builtin configuration provided by this library.
• Builds README.md and adds it to git
• Executes lint-staged.
  • format (If not opted out) and add to git
  • lint
  • test (executes test related to changed files)
• If opted in, executes validation script.

Properties

reset

Reverses modifications made by this library. (Please note that deleted files are not reversed. You should recover them from git repo)

Example

$ npx moe-scripts reset

test

Test project using Jest

• Sets BABEL_ENV and NODE_ENV to test.
• If not in CI, precommit stage, or following arguments are not present --no-watch, --coverage, --updateSnapshot or --watchAll, watches changes.
• If no config provided (--config, jest.config.js etc.) uses builtin configuration provided by this library.

Properties

Example

$ npm run test
$ npx moe-scripts test

travis-after-success

WIP

Example

$ npx travis-after-success

validate

Validates project.

Executes following tasks based on the event being in:

To avoid redundant execution, lint and test are not executed in precommit stage because those are executed in precommit script already.

Properties

Example

$ npm run validate my-custom-validator
$ npx moe-scripts validate
$ npx moe-scripts validate my-custom-validator,second-validator