@form8ion/project

project

opinionated scaffolder for new projects

Table of Contents

• Features
• Usage
  • Installation
  • Consumption in a CLI tool
  • Example
    • Import
    • Execute
  • API
    • languages (optional)
    • vcsHosts (optional)
    • dependencyUpdaters (optional)
• 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 chosen VCS Host details
• scaffolds the chosen CI service config
• scaffolds the project README.md
• scaffolds language specific details by delegating to provided scaffolder functions

Usage

Installation

$ npm install @form8ion/project --save-prod

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

import {lift, questionNames, scaffold} from '@form8ion/project';

Execute

await scaffold({
  decisions: {
    [questionNames.PROJECT_NAME]: 'my-project',
    [questionNames.LICENSE]: 'MIT',
    [questionNames.VISIBILITY]: 'Public',
    [questionNames.DESCRIPTION]: 'My project',
    [questionNames.GIT_REPO]: false,
    [questionNames.COPYRIGHT_HOLDER]: 'John Smith',
    [questionNames.COPYRIGHT_YEAR]: '2022',
    [questionNames.PROJECT_LANGUAGE]: 'foo'
  },
  plugins: {
    dependencyUpdaters: {
      bar: {scaffold: options => options}
    },
    languages: {
      foo: {scaffold: options => options}
    },
    vcsHosts: {
      baz: {
        scaffold: options => options,
        prompt: () => ({repoOwner: 'form8ion'})
      }
    }
  }
});

await lift({
  projectRoot: process.cwd(),
  results: {},
  enhancers: {foo: {test: () => true, lift: () => ({})}},
  vcs: {}
});

API

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

Takes a single options object as an argument, containing:

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. Official options are provided in the awesome list.

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
      • 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
    • 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. Official options are provided in the awesome list.

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
      • 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. Official options are provided in the awesome list.

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
      • 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

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