trevtrich / project-scaffolder

opinionated scaffolder for new projects

project-scaffolder

opinionated scaffolder for new projects

Table of Contents

• Features
• Usage
  • Installation
  • Consumption in a CLI tool
    • Example
    • Options
      • languages (optional)
      • vcsHosts (optional)
      • dependencyUpdaters (optional)
      • overrides (optional)
        • copyrightHolder
        • githubAccount
• Contributing
  • Dependencies
  • Verification
• Related Projects
• Inspiration

Features

• configures generic editor settings through EditorConfig
• scaffolds license details
• scaffolds VCS details if git is chosen
• scaffolds the VCS Host details if GitHub is chosen
• scaffolds CI server config if Travis is chosen
• scaffolds the project README.md
• scaffolds language specific details by delegating to provided scaffolder functions
  • Examples:
    • JavaScript

Usage

Installation

$ npm install @travi/project-scaffolder -S

Consumption in a CLI tool

This scaffolder is intended to be used as a CLI tool, but it is left up to the consumer to provide the actual CLI wrapper. My sub-command for commander is an example of such a wrapper.

Example

import program from 'commander';
import {scaffold as scaffoldJavaScript} from '@travi/javascript-scaffolder';
import {scaffold} from '@travi/project-scaffolder';

program
  .command('scaffold')
  .description('scaffold a new project')
  .action(() => scaffold({
    languages: {
      JavaScript: options => scaffoldJavaScript(options)
    },
    overrides: {copyrightHolder: 'John Smith'}
  }).catch(err => {
    console.error(err);
    process.exitCode = 1;
  }));

Options

This is an opinionated scaffolder, but there are some aspects that are configurable in order to support multiple contexts.

languages (optional)

provides the languages to choose from and the functions to perform the scaffolding for the chosen language. if no languages are provided, Other will be the only choice presented. Choosing Other will perform no language-specific scaffolding.

object:

• keys: string Name of the language
• values: function that scaffolds language specific details
  • receives an options object as its first argument to pass along answers to the project-level prompts
    • projectRoot: string path of the working directory where the CLI command was executed
    • projectName: string name chosen for the project. defaults to the directory name.
    • vcs: object details about the VCS host
      • host: string host name. defaults to GitHub
      • name: string repository name. equal to projectName
      • owner: string account name on the host service for the repository owner. defaults to $ git config github.user or the overridden value
    • visibility: string Public or Private. defaults to Private
    • license: string identifier of the chosen SPDX License or UNLICENSED
    • ci: string name of the chosen CI service. defaults to Travis
    • description: string short summary of the project

vcsHosts (optional)

provides the vcs hosts to choose from and the functions to perform the scaffolding for the chosen host. if no hosts are provided, Other will be the only choice presented. Choosing Other will perform no host-specific scaffolding.

object:

• keys: string Name of the vcs host
• values: object
  • prompt: function (required) prompts for host specific details
    • MUST return an object of the prompt answers, which MUST include the name of the account for the host that owns the repo as repoOwner
  • scaffolder: function (required) scaffolds the host options
    • receives an options object as its first argument to pass along answers to the project-level prompts
      • host: string name of the chosen host, as provided in the key of the vcsHosts object
      • name: string name chosen for the project. defaults to the directory name.
      • owner: the account name of the owner of the repo on the host, as returned from the prompt function
      • projectRoot: string path of the working directory where the CLI command was executed
      • projectType: string primary language for the project
      • description: string brief summary of the project
      • homepage: string url of the project homepage
  • public: boolean (optional) whether this host should be presented as a public option
  • private: boolean (optional) whether this host should be presented as a private option

dependencyUpdaters (optional)

provides the dependency updaters to choose from and the functions to perform the scaffolding for the chosen updater service. if no updater services are provided, Other will be the only choice presented. Choosing Other will perform no updater-service-specific scaffolding.

object:

• keys: string Name of the dependency update service
• values: object
  • scaffolder: function (required) scaffolds the host options
    • receives an options object as its first argument to pass along answers to the project-level prompts
      • projectRoot: string path of the working directory where the CLI command was executed
    • vcs: object details about the VCS host
      • host: string host name. defaults to GitHub
      • name: string repository name. equal to projectName
      • owner: string account name on the host service for the repository owner. defaults to $ git config github.user or the overridden value

overrides (optional)

copyrightHolder

string enables setting the value of the prompt default for the copyright holder. if not provided, the default will be empty.

githubAccount

string enables setting the GitHub account for the prompt default to define the owner of scaffolded repositories. if not provided, the default will use the result of $ git config github.user

Contributing

Dependencies

$ nvm install
$ npm install

Verification

$ npm test

Related Projects

• javascript-scaffolder
• scaffolder-sub-command
• github-scaffolder
• travis-scaffolder-javascript
• cli

Inspiration

• Yeoman
• Lass