boiler

Boilerplate generator framework & low-code power tool 🛠️

npm install -g boiler-dev

Generator lifecycle

| Action | Command | | ------------------------------ | ----------------------------------------- | | Start a new TypeScript project | boiler new [project-name] | | Change directory to project | cd [project-name] | | Install and run generator | boiler generate [git url] | | Update generator | boiler update [boiler/generator-name] | | Regenerate installed generator | boiler generate [boiler/generator-name] | | Create new generator | boiler new [boiler/generator-name] | | Commit and push generator | boiler commit [boiler/generator-name] | | Status of generator repos | boiler status [boiler/generator-name] |

When commands are run without arguments, it will run across all installed generators.

For successive generate calls, boiler will regenerate with saved user input unless the --new flag is specified.

Important files

| Path | Description | | -------------- | ---------------------------------------------------------- | | .boiler.json | Record of generator runs, with version and user input data | | boiler/ | Installed generator repos |

Usage examples

Install boiler

npm install -g boiler-dev

Run generator

1. cd to your project
2. boiler generate [git repo]

The generate command automatically installs new generators.

Generator repos are cloned to the boiler directory within your project. The boiler directory is like node_modules for your generators.

ℹ️ Explore example generators on the boiler-dev GitHub org.

Update and regenerate

1. cd to your project
2. boiler update [boiler/my-generator]
3. boiler generate [boiler/my-generator]

New generator

1. cd to your project
2. boiler new boiler/my-generator

Develop generator

1. Modify boiler/my-generator/boiler.ts (see next section for API details)
2. boiler generate boiler/my-generator
3. boiler commit boiler/my-generator "First commit"

Generator API — boiler.ts

Each generator repo must have a boiler.ts or boiler.js file:

import {
  InstallBoiler,
  PromptBoiler,
  GenerateBoiler,
  UninstallBoiler,
} from "boiler-dev"

export const install: InstallBoiler = async ({
  files,
  rootDirPath,
}) => {}

export const prompt: PromptBoiler = async ({
  files,
  rootDirPath,
}) => {
  const prompts = []
  return prompts
}

export const generate: GenerateBoiler = async ({
  answers,
  files,
  rootDirPath,
}) => {
  const actions = []
  return actions
}

export const uninstall: UninstallBoiler = async ({
  answers,
  files,
  rootDirPath,
}) => {}

Prompt

The prompt function returns an array of "prompts" that define user input to retrieve.

Prompts are essentially an array of Inquirer.js Questions.

Generate

The generate function returns an array of "actions" necessary to install the boilerplate.

Actions are a convenience; feel free to run your own async code within installBoiler and return nothing.

Write file action

actions.push({
  action: "write",
  path: "bin/hi",
  source: "#!/usr/bin/env node",
  bin: true,
})

ℹ️ The bin option runs chmod +x on the file.

Merge JSON action

actions.push({
  action: "merge",
  path: "package.json",
  source: { hi: true },
})

ℹ️ The merge functionality comes from deepmerge.

NPM install action

actions.push({
  action: "npmInstall",
  source: ["typescript"],
  dev: true,
})

New project

When not used within a boiler/ directory, the boiler new command creates a new TypeScript project to kick things off:

boiler new my-project

ℹ️ This is a shortcut for manually running the following generators:

• package-json-boiler
• ts-boiler
• eslint-prettier-ts-boiler
• release-boiler
• mocha-boiler
• vscode-watch-boiler