@travi/project-scaffolder

opinionated scaffolder for new projects

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@travi/project-scaffolder
31810.1.2a year ago4 years agoMinified + gzip package size for @travi/project-scaffolder in KB

Readme

project-scaffolder
opinionated scaffolder for new projects

Codecov !Node CI Workflow Statusgithub-actions-ci-badgegithub-actions-ci-link

Table of Contents

Installation Consumption in a CLI tool
* [Example](#example)
* [Options](#options)
  * [`languages` (_optional_)](#languages-optional)
  * [`vcsHosts` (_optional_)](#vcshosts-optional)
  * [`dependencyUpdaters` (_optional_)](#dependencyupdaters-optional)
  * [`overrides` (_optional_)](#overrides-optional)
    * [`copyrightHolder`](#copyrightholder)
    * [`githubAccount`](#githubaccount)
Dependencies Verification

Features

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


!npmnpm-badgenpm-link !Snyk Vulnerabilities for npm packagesnyk-badgesnyk-link !nodenode-badge !MIT licenselicense-badgelicense-link

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} from '@travi/project-scaffolder';

program
  .command('scaffold')
  .description('scaffold a new project')
  .action(() => scaffold({
    languages: {
      foo: options => (opts => ({
        projectDetails: {homepage: 'https://website.com'},
        tags: ['foo', 'bar', 'baz'],
        badges: {
          contribution: {
            badgeName: {
              text: 'Hover text for the badge',
              link: 'http://link-to-related-service.com',
              img: 'image to render as badge'
            }
          },
          status: {},
          consumer: {}
        },
        ...opts.vcs && {
          vcsIgnore: {
            files: ['foo.txt', 'bar.txt'],
            directories: ['build/', 'dependencies/']
          }
        },
        nextSteps: [{summary: 'something extra to do manually'}],
        verificationCommand: 'terminal command to run after scaffolding is complete'
      }))(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. 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](https://en.wikipedia.org/wiki/Version_control)
  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` or the [overridden value](#githubaccount)
* `visibility`: __string__ `Public` or `Private`. defaults to `Private`
* `license`: __string__ identifier of the chosen [SPDX License](https://spdx.org/licenses/)
  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
  * `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. 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](https://en.wikipedia.org/wiki/Version_control)
  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` or the [overridden value](#githubaccount)
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


!Conventional Commits
commit-convention-badgecommit-convention-link !Commitizen friendlycommitizen-badgecommitizen-link semantic-release !PRs Welcomeprs-badgeprs-link !Renovaterenovate-badgerenovate-link

Dependencies

$ nvm install
$ npm install

Verification

$ npm test

Related Projects

Inspiration