Home

Awesome

Gardener gardener

Build Status NPM Downloads

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

Getting Started

Preparation

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-unresolved -->
/* 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<br> Default: fancy-log

Attach custom logger.

skip

Type: array<br> Default: []

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

cwd

Type: string<br> 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<br> 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.