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
- Scans dependencies for vulnerabilities using npm audit
- 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
const gardener = require('js-gardener');
if (require.main === module) {
gardener().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.jsonstructure
: Enforce that test file structure matches lib contentaudit
: Runs npm audit and throws errors for old or important issues.eslint
: Ensure code is according to eslint definitions.yamllint
: Ensure yaml files are passing lintdepcheck
: Ensure dependencies are installed as specified in package.jsondepused
: 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.