Skip to content

ozum/moe-scripts

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

205 Commits
@types
@types
 
 
src
src
 
 
.all-contributorsrc
.all-contributorsrc
 
 
.editorconfig
.editorconfig
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.npmignore
.npmignore
 
 
.prettierignore
.prettierignore
 
 
.prettierrc.js
.prettierrc.js
 
 
.travis.yml
.travis.yml
 
 
CHANGELOG.md
CHANGELOG.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
README.hbs
README.hbs
 
 
README.md
README.md
 
 
___TODO.txt
___TODO.txt
 
 
appveyor.yml
appveyor.yml
 
 
babel.js
babel.js
 
 
commitlint.js
commitlint.js
 
 
config.js
config.js
 
 
eslint.js
eslint.js
 
 
husky.js
husky.js
 
 
jest.config.js
jest.config.js
 
 
jest.js
jest.js
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
prettier.js
prettier.js
 
 
tsconfig.json
tsconfig.json
 
 
tslint.json
tslint.json
 
 

Repository files navigation

moe-scripts

Commitizen friendly

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 ✓ TS TSLint configuration file
.eslintrc ✓ ESLint ESLint configuration file
tsconfig.json ✓ TS TypeScript configuration file. (Not created as link, for IDEs
tsconfig-test.json ✓ ✓ TS 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

Name Type Default Description
[--bundle]

If present, uses rollup, otherwise TypeScript or Babel.
[--outDir] string "lib"

TS Output destination for built files.
[--no-clean]

TS If present, does not clean target directory.
[--out-dir] string "lib"

Babel Output destination for built files.
[OTHERS]

All CLI options used by related binary. (tsc, babel or rollup)

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

Name Description
[OTHERS]

All CLI options used by related binary. (jsdoc2md)

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

Name Description
[--no-write]

If provided files are not written to disk. (Default is write to disk).
[OTHERS]

All CLI options used by related binary. (prettier)

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

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 ✓ TS TSLint configuration file
.eslintrc ✓ ESLint ESLint configuration file
tsconfig.json ✓ TS TypeScript configuration file. (Not created as link, for IDEs
tsconfig-test.json ✓ ✓ TS TypeScript configuration file used during testing

Properties

Name Description
[...files]

Files to lint
[--no-cache]

ESLint Disables ESLint --cache arg which is added by this script.
[OTHERS]

All CLI options used by related binary. (TSLint or ESLint)

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

Name Description
[...files]

Files to lint
[--no-cache]

ESLint Disables ESLint's --cache arg which is added by this script.
[OTHERS]

All CLI options used by related binary. (TSLint or ESLint)

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

Name Description
[OTHERS]

All CLI options used by related binary. (prettier)

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

Name Description
[--no-watch]

If provided, works once. (Default is watch mode)
[OTHERS]

All CLI options used by related binary. (jest)

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:

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.

Properties

Name Description
[0]

If provided vomma separated list of npm script names to run.

Example

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

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

2 watching

Forks

0 forks
Report repository

Releases

90 tags

Packages

No packages published

Languages