CONFDOCS.md

Codebase Configuration Documentation

Documents configuration tasks managed by robo-config.

Plugin @blackflux/robo-config-plugin

• 📂 assorted/@docker-lambda
  • 📂 docker/#serverless
    • 📋 docker/sls-manage
    • 📋 docker/sls-docker
• 📂 assorted/@npm-opensource
  • 📂 struct/#npm-default
    • 📋 struct/force-gardener
    • 📂 struct/#npm-base
      • 📋 struct/test-reg
      • 📋 struct/test-hot
      • 📋 struct/template-readme
      • 📋 struct/template-mocharc
      • 📋 struct/template-index-test
      • 📋 struct/template-index
      • 📋 struct/template-eslintrc
      • 📋 struct/template-eslint-config
  • 📂 semantic-release/#npm-default
    • 📋 semantic-release/commit-conventions
  • 📂 package/#npm-default
    • 📋 package/npm-default_merge-shallow
    • 📋 package/npm-default_merge-deep
    • 📋 package/npm-default_default-shallow
    • 📋 package/npm-default_default-deep
  • 📂 npm/#npm-default
    • 📋 npm/npmignore
  • 📂 license/#opensource
    • 📋 license/MIT-package
    • 📋 license/MIT-file
  • 📂 jetbrains/#default
    • 📋 jetbrains/exclude-coverage-folder
  • 📂 gitignore/#npm-default
    • 📋 gitignore/npm-default
  • 📂 gally/#npm-default
    • 📋 gally/two-branch
  • 📂 editor/#default
    • 📋 editor/two-space
  • 📂 dependabot/#npm-default
    • 📋 dependabot/js-instant
  • 📂 circleci/#npm-default
    • 📋 circleci/two-branch
  • 📂 c8/#default
    • 📋 c8/default_merge-shallow
    • 📋 c8/default_merge-deep
    • 📋 c8/default_default-shallow
    • 📋 c8/default_default-deep
  • 📂 badges/#npm-opensource
    • 📋 badges/npm-status
    • 📋 badges/npm-downloads
    • 📋 badges/circleci

📂 assorted/@docker-lambda (index)

Manage AWS Lambda docker runner for project.

Targets	Requires
project ├─ manage.sh └─ docker    └─ Dockerfile	docker serverless

📂 docker/#serverless (index)

Manage docker test configuration for serverless project.

Targets	Requires
project ├─ manage.sh └─ docker    └─ Dockerfile	docker serverless

📋 docker/sls-manage (index)

Updating manage.sh using overwrite.

• Spawn docker container for serverless testing and deploying.

Targets	Requires
project └─ manage.sh	docker serverless

📋 docker/sls-docker (index)

Updating docker/Dockerfile using overwrite.

• Docker environment definition for running tests in AWS Lambda container.

Targets	Requires
project └─ docker    └─ Dockerfile	docker serverless

📂 assorted/@npm-opensource (index)

Manage various configuration files for an open source npm package on github.

Targets	Requires	Variables
project ├─ .circleci │  └─ config.yml ├─ .dependabot │  └─ config.yml ├─ .idea │  └─ ${projectName}.iml ├─ .c8rc.json ├─ .editorconfig ├─ eslint.config.js ├─ .eslintrc.json ├─ .gally.json ├─ gardener.js ├─ .gitignore ├─ LICENSE ├─ .mocharc.yml ├─ .npmignore ├─ package.json ├─ README.md ├─ .releaserc.json ├─ src │  └─ index.js └─ test    ├─ hot.js    ├─ index.spec.js    └─ reg.js	javascript js-gardener mocha chai eslint semantic-release npm npm-published jetbrains c8 git circleci gally github dependabot yarn	packageName nccExclude nccEnabled nodeVersion repoKey ownerName projectName owner mergeBot

📂 struct/#npm-default (index)

Manage basic project structure for npm package on github.

Targets	Requires	Variables
project ├─ eslint.config.js ├─ .eslintrc.json ├─ gardener.js ├─ .mocharc.yml ├─ README.md ├─ src │  └─ index.js └─ test    ├─ hot.js    ├─ index.spec.js    └─ reg.js	javascript js-gardener mocha chai eslint	packageName

📋 struct/force-gardener (index)

Updating gardener.js using overwrite.

• Manage gardener.js file for js-gardener.

Targets	Requires
project └─ gardener.js	javascript js-gardener

📂 struct/#npm-base (index)

Manage basic project structure for npm package on github.

Targets	Requires	Variables
project ├─ eslint.config.js ├─ .eslintrc.json ├─ .mocharc.yml ├─ README.md ├─ src │  └─ index.js └─ test    ├─ hot.js    ├─ index.spec.js    └─ reg.js	javascript mocha chai eslint	packageName

📋 struct/test-reg (index)

Updating test/reg.js using overwrite.

• Create register file.

Targets	Requires
project └─ test    └─ reg.js	javascript

📋 struct/test-hot (index)

Updating test/hot.js using overwrite.

• Create loader file.

Targets	Requires
project └─ test    └─ hot.js	javascript

📋 struct/template-readme (index)

Updating README.md using create-only.

• Create README.md template file.

Targets	Variables
project └─ README.md	packageName

📋 struct/template-mocharc (index)

Updating .mocharc.yml using create-only.

• Create options file for mocha tests.

Targets	Requires
project └─ .mocharc.yml	javascript mocha

📋 struct/template-index-test (index)

Updating test/index.spec.js using create-only.

• Create package template index.spec.js test file.

Targets	Requires
project └─ test    └─ index.spec.js	javascript chai

📋 struct/template-index (index)

Updating src/index.js using create-only.

• Create package template index.js file.

Targets	Requires
project └─ src    └─ index.js	javascript

📋 struct/template-eslintrc (index)

Updating .eslintrc.json using overwrite.

• Create configuration file for eslint enforcing opinionated, best practices.

Targets	Requires
project └─ .eslintrc.json	javascript eslint

📋 struct/template-eslint-config (index)

Updating eslint.config.js using overwrite.

• Create configuration file for eslint enforcing opinionated, best practices.

Targets	Requires
project └─ eslint.config.js	javascript eslint

📂 semantic-release/#npm-default (index)

Manage semantic-release configuration for npm package on github.

Targets	Requires
project └─ .releaserc.json	semantic-release

📋 semantic-release/commit-conventions (index)

Updating .releaserc.json using overwrite.

• Slightly extended release commit convention for semantic-release.

Targets	Requires
project └─ .releaserc.json	semantic-release

📂 package/#npm-default (index)

Manage package.json for npm package on github.

Targets	Requires	Variables
project └─ package.json	javascript	nccExclude nccEnabled nodeVersion repoKey packageName

📋 package/npm-default_merge-shallow (index)

Updating package.json using merge-shallow.

• Set various entries.

Targets	Requires	Variables
project └─ package.json	javascript	nccExclude nccEnabled

📋 package/npm-default_merge-deep (index)

Updating package.json using merge-deep.

• Set various entries.

Targets	Requires	Variables
project └─ package.json	javascript	nodeVersion repoKey packageName

📋 package/npm-default_default-shallow (index)

Updating package.json using default-shallow.

• Set defaults for various entries.

Targets	Requires
project └─ package.json	javascript

📋 package/npm-default_default-deep (index)

Updating package.json using default-deep.

• Set defaults for various entries.

Targets	Requires
project └─ package.json	javascript

📂 npm/#npm-default (index)

Manage npm configuration for npm package on github.

Targets	Requires
project └─ .npmignore	npm npm-published

📋 npm/npmignore (index)

Updating .npmignore using unique-top.

• Inject comment into .npmignore explaining when to use it.

Targets	Requires
project └─ .npmignore	npm npm-published

📂 license/#opensource (index)

Manage license configuration for open source project.

Targets	Requires	Variables
project ├─ LICENSE └─ package.json	npm	ownerName repoKey

📋 license/MIT-package (index)

Updating package.json using merge-shallow.

• Link MIT license file into npm configuration.

Targets	Requires	Variables
project └─ package.json	npm	ownerName repoKey

📋 license/MIT-file (index)

Updating LICENSE using overwrite.

• Generate MIT license file.

Targets	Variables
project └─ LICENSE	ownerName

📂 jetbrains/#default (index)

Manage WebStorm configuration.

Targets	Requires	Variables
project └─ .idea    └─ ${projectName}.iml	jetbrains c8	projectName

📋 jetbrains/exclude-coverage-folder (index)

Updating .idea/${projectName}.iml (if exists) using xml-merge.

• Mark coverage Folder as excluded in Jetbrains.

Targets	Requires	Variables
project └─ .idea    └─ ${projectName}.iml	jetbrains c8	projectName

📂 gitignore/#npm-default (index)

Manage gitignore configuration for npm package on github.

Targets	Requires
project └─ .gitignore	git

📋 gitignore/npm-default (index)

Updating .gitignore using unique-top.

• Inject recommended entries into gitignore file.
• Default ignores for JetBrains IDE.
• Default ignores for OSX
• Default ignores for NodeJs

Targets	Requires
project └─ .gitignore	git

📂 gally/#npm-default (index)

Manage gally configuration for npm package on github.

Targets	Requires	Variables
project └─ .gally.json	circleci gally github	owner mergeBot repoKey

📋 gally/two-branch (index)

Updating .gally.json using overwrite.

• Restrictive two-branch config.

Targets	Requires	Variables
project └─ .gally.json	circleci gally github	owner mergeBot repoKey

📂 editor/#default (index)

Manage editor configuration for project.

Targets
project └─ .editorconfig

📋 editor/two-space (index)

Updating .editorconfig using overwrite.

• Two space line indentation.
• Set lf line endings.
• Set utf8 encoding.
• Remove unnecessary whitespaces.

Targets
project └─ .editorconfig

📂 dependabot/#npm-default (index)

Manage dependabot configuration for npm package on github.

Targets	Requires
project └─ .dependabot    └─ config.yml	dependabot github javascript

📋 dependabot/js-instant (index)

Updating .dependabot/config.yml using overwrite.

• Configure dependabot to instantly merge javascript dependency updates into the dev branch.

Targets	Requires
project └─ .dependabot    └─ config.yml	dependabot github javascript

📂 circleci/#npm-default (index)

Manage circleci configuration for npm package on github.

Targets	Requires
project └─ .circleci    └─ config.yml	npm yarn gally github circleci dependabot semantic-release

📋 circleci/two-branch (index)

Updating .circleci/config.yml using overwrite.

• Restrictive two-branch circleci config.

Targets	Requires
project └─ .circleci    └─ config.yml	npm yarn gally github circleci dependabot semantic-release

📂 c8/#default (index)

Manage .c8rc.json for c8 coverage testing.

Targets	Requires
project └─ .c8rc.json	javascript

📋 c8/default_merge-shallow (index)

Updating .c8rc.json using merge-shallow.

• Set various entries.

Targets	Requires
project └─ .c8rc.json	javascript

📋 c8/default_merge-deep (index)

Updating .c8rc.json using merge-deep.

• Set various entries.

Targets	Requires
project └─ .c8rc.json	javascript

📋 c8/default_default-shallow (index)

Updating .c8rc.json using default-shallow.

• Set defaults for various entries.

Targets	Requires
project └─ .c8rc.json	javascript

📋 c8/default_default-deep (index)

Updating .c8rc.json using default-deep.

• Set defaults for various entries.

Targets	Requires
project └─ .c8rc.json	javascript

📂 badges/#npm-opensource (index)

Add badged for npm open source package on github.

Targets	Requires	Variables
project └─ README.md	npm-published circleci	packageName repoKey

📋 badges/npm-status (index)

Updating README.md using merge-below-title.

• Display npm status badge in README.

Targets	Requires	Variables
project └─ README.md	npm-published	packageName

📋 badges/npm-downloads (index)

Updating README.md using merge-below-title.

• Display npm downloads badge in README.

Targets	Requires	Variables
project └─ README.md	npm-published	packageName

📋 badges/circleci (index)

Updating README.md using merge-below-title.

• Display circleci badge in README.

Targets	Requires	Variables
project └─ README.md	circleci	repoKey

---

Requires

docker (link)

Container Platform.

Docker is a computer program that performs operating-system-level virtualization. Makes it for example possible to easily create and tear down complex test setups.

serverless (link)

Serverless Framework.

The Serverless Framework is a free and open-source web framework that was developed for building serverless applications.

javascript (link)

Programming Language.

JavaScript, often abbreviated as JS, is a high-level, interpreted programming language that conforms to the ECMAScript specification. It is characterized as dynamic, weakly typed, prototype-based and multi-paradigm.

js-gardener (link)

NodeJs Project Management.

Enforces and helps setting up best practices around NodeJs projects. 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.

mocha (link)

JavaScript test framework.

Mocha is a JavaScript test framework for Node.js programs, featuring browser support, asynchronous testing, test coverage reports, and use of any assertion library.

chai (link)

JavaScript assertion library.

Chai is a BDD / TDD assertion library for node and the browser that can be paired with any javascript testing framework.

eslint (link)

Linting for JavaScript.

JSLint is a static code analysis tool used in software development for checking if JavaScript source code complies with coding rules.

semantic-release (link)

Automates npm package release workflow.

Automates the package release workflow including:

• determining the next version number
• generating the release notes
• publishing the package

npm (link)

Javascript package repository.

Requires the project to be conform with the npm standard, i.e. contain a package.json file. Does not require the project to be published to npm.

npm-published (link)

Javascript package repository published.

Requires the project to be published to npm either as a private or public package.

jetbrains (link)

Collection of various IDEs.

Collection of various IDEs. There exists one for every major programming language and they are all very similar (i.e. shortcuts, layout), which makes them great when switching languages.

c8 (link)

Coverage testing for javascript projects.

A major coverage testing framework for javascript. Comes with all the bells and whistles.

git (link)

Version control system.

The most used version control system. Not to be confused with github (which uses git).

circleci (link)

Run automated jobs using docker containers.

Allows set up for ci/cd using docker containers. Automates development process quickly, safely, and at scale.

gally (link)

Automation around github.com Repository Management

Allows management of github.com repositories through configuration. Very powerful when you need to synchronize settings across multiple repositories.

github (link)

Major development platform powered by git.

GitHub is a code hosting platform for collaboration and version control. Lets you and others work together on projects.

dependabot (link)

Automatic dependency updates.

Makes dependency updates very easy by automatically creating pull requests in your repo. All major programming languages are supported or work is done towards supporting them.

yarn (link)

Dependency management similar to npm.

Very similar functionality to npm cli.

---

Variables

packageName : string

Name of the package on npm.

The name of the project as published to npm. Note that for scoped packages the name can differ significantly from the repo name.

nccExclude : array

Default: ``

Exclude packages from ncc compilation.

nccEnabled : boolean

Enable ncc for service.

Uses NCC to compile service. Please ensure that the service still works after ncc compilation.

nodeVersion : string

The minimum node version targeted.

The minimum nodejs version that the project targets.

repoKey : string

Repository key.

The repository key contains the owner or organization of the project and the repository name itself, separated by a slash.

ownerName : string

Name of the owner of this project.

The owner name of the project is the name of the person or organization publishing the project under their license.

projectName : string

Name of the project.

The project name is in most cases identical to the repository name.

owner : string

The owner of the code on github.

The code owner is the gatekeeper of the project, ultimately responsible for all changes.

mergeBot : string

The github name of the bot used for automatic merging.

---

Targets

manage.sh

🔺 docker

🔹 other

Prepare project to run tests.

File starts docker container(s) with necessary setup to execute the project tests.

docker/Dockerfile (link)

🔺 docker

🔹 other

Main docker container configuration file.

Contains instructions for the main docker container this repository uses for testing.

gardener.js (link)

🔺 js-gardener, javascript

🔹 other

Runner for js-gardener.

Execute all configured js-gardener tasks.

test/reg.js

🔹 other

Registration hook to load custom loader.

test/hot.js

🔹 other

Loader to allow hot reloading of files for testing.

README.md (link)

🔹 nostruct

Project readme file.

Contains lots of information about the project itself.

.mocharc.yml (link)

🔺 mocha, javascript

🔹 list

Mocha test configuration file.

test/index.spec.js

🔺 javascript

🔹 other

Main project test file.

Main test file for the project. At the very least tests signature of what is exposed.

src/index.js

🔺 javascript

🔹 other

Main project file.

Main file for the project. Exposes functionality for libraries.

.eslintrc.json (link)

🔺 eslint

🔹 json

Configuration file for eslint.

eslint.config.js (link)

🔺 eslint

🔹 nostruct

Configuration file for eslint.

.releaserc.json (link)

🔺 semantic-release

🔹 json

Configuration for semantic-release.

Configuration file for semantic-release and plugins

package.json (link)

🔺 npm

🔹 json

Configuration for npm package.

.npmignore (link)

🔺 npm, npm-published

🔹 list

Config to exclude files from npm package.

Note that this file is mostly not required. Use whitelisting instead. See here for more information.

LICENSE (link)

🔹 nostruct

Project License file.

Specify the license the project is published under. Can be set to unlicensed as well.

.idea/${projectName}.iml (link)

🔺 jetbrains

🔹 xml

Module Library configuration file for JetBrains IDE.

.gitignore (link)

🔺 git

🔹 list

Exclude files from being tracked.

Specifies files intentionally untracked by git.

.gally.json (link)

🔺 gally, github

🔹 json

Configuration file for gally.

Includes detailed configuration for github project structure.

.editorconfig (link)

🔹 other

Defines file formatting.

Defines file formatting that an IDE can pick up and use to format project files.

.dependabot/config.yml (link)

🔺 dependabot

🔹 yml

Configuration file for dependabot.

.circleci/config.yml (link)

🔺 circleci

🔹 yml

Configuration file for circleci.

.c8rc.json (link)

🔺 c8

🔹 json

Configuration for c8 package.

---

Strategies

overwrite

🔹 any

Simply replace the old with the new content.

create-only

🔹 any

Does nothing when the file is already present, otherwise creates it.

merge-shallow

🔹 json, yml

Does a shallow merge aka Object.assign().

Useful when specific keys of the target need to be overwritten.

merge-deep

🔹 json, yml

Does a "smart" deep merge.

This will not work as desired for all object deep merging, but should for many cases.

default-shallow

🔹 json, yml

Similar to merge-shallow, but keeps existing values instead of overwriting.

Useful to ensure specific keys of the target are present without overwriting existing content.

default-deep

🔹 json, yml

Similar to merge-deep, but keeps existing values instead of overwriting.

Useful to ensure specific keys of the target are present without overwriting existing content.

unique-top

🔹 list

Merges content at the top of the file and removes existing, duplicate lines.

Useful for managing e.g. .gitignore when the original content should be kept.

xml-merge

🔹 xml

Does a "smart" deep merge.

This will not work as desired for all xml merging, but should for many cases.

merge-below-title

🔹 list, nostruct

Merges content below title.