js-gardener

Gardener

Enforces highest code quality and minimizes package setup and maintenance complexity - so you can focus on writing code. Highly recommended if you are getting started with a new package and extremely useful if you are maintaining multiple packages.

What it does

• Enforces best code style practises using ESLint and YAMLlint
• Automates and assists with config generation and best practices via robo-config
• Provides various integrity tests (e.g. checks for un-used dependencies)
• Enforces 100% test coverage using Nyc

Getting Started

Preparation

• Create New Project (e.g. using Webstorm)
• Create New Repository on Github
• Run git init, git remote add origin URL, git checkout -b master
• Run npm init and fill in details

Install Gardener

$ npm install --save-dev js-gardener

Run Basic Setup

Create gardener.js in the root folder with the following contents

/* eslint-disable import/no-extraneous-dependencies */
import gardener from 'js-gardener';
import fs from 'smart-fs';
import process from 'process';

if (process.argv[1] === fs.filename(import.meta.url)) {
  gardener({
    skip: []
  }).catch(() => process.exit(1));
}

Now create a .roboconfig.json file. Recommended for OpenSource npm packages is the following:

{
  "@blackflux/robo-config-plugin": {
    "tasks": [
      "assorted/@npm-opensource"
    ],
    "variables": {
      "repoKey": "org-name/repo-name",
      "packageName": "repo-name",
      "projectName": "repo-name",
      "owner": "owner-name",
      "ownerName": "Owner Name",
      "mergeBot": "mergebot-name"
    }
  }
}

Then run

$ node gardener

This will generate some files and alter your existing package.json file.

Create your files in the src folder and corresponding tests in the test folder (Mocha and Chai work great), and ensure everything works fine by running npm test. Finalize your README.md and package.json and commit and push to GitHub.

Run Tests Locally

To run all tests locally

$ npm t

and in debug mode with

$ npm t -- --debug

All Mocha options can be passed using double dash. E.g. to run individual tests

$ npm run test-simple -- -g "Partial Test Description Here"

To auto fix fixable eslint problems run

$ node gardener.js --fix

Structure

Folders - Write your tests in the test and your code in the src folder. The lib folder is used as the build target. Test files must be of format *.spec.js.

Branches - You release branch is master. Develop against dev or feature branches. When you are ready for a release, merge your changes into master.

Coverage

Customize the nyc section in your package.json

To completely ignore files from coverage put them into the exclude section in nyc.

Options

logger

Type: logger
Default: fancy-log

Attach custom logger.

skip

Type: array
Default: []

Array of tasks to skip. Should not be necessary to use unless you really need to. Available tasks are:

• robo: Apply robo-config configuration file.
• package: Alter package.json
• structure: Enforce that test file structure matches lib content
• eslint: Ensure code is according to eslint definitions.
• yamllint: Ensure yaml files are passing lint
• depcheck: Ensure dependencies are installed as specified in package.json
• depused: Ensure all installed dependencies are used

cwd

Type: string
Default: process.cwd()

Specify the directory to run the tests against. Useful if you have multiple packages that you manage centralized from a parent folder.

docker

Type: boolean
Default: false

Execution will fail if not inside docker container, when set to true.

Ignore Files

.eslintignore

Define files which should be excluded for eslint. Always excluded files can be found here.

.depunusedignore

Define packages that should be excluded from usage check. Useful when a false negative is detected, e.g. for plugins where usage is defined in configuration. Always excluded packages can be found here.

.structignore

Define test files that should not be checked for structure. Usually not necessary. Always excluded test files can be found here.

Example Projects

This project utilizes itself for testing - how cool is that? All other projects published under blackflux also utilize this framework.

Example project using js-gardener and lambda-tdd can be found here.

All blackflux npm packages also utilize Gardener.