Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/form8ion/project

opinionated scaffolder for new projects
https://github.com/form8ion/project

Last synced: 19 days ago
JSON representation

opinionated scaffolder for new projects

Awesome Lists containing this project

README 

        
# project



opinionated scaffolder for new projects



[![Node CI Workflow Status][github-actions-ci-badge]][github-actions-ci-link]

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/form8ion/project/badge)](https://securityscorecards.dev/viewer/?uri=github.com/form8ion/project)

[![Codecov][coverage-badge]][coverage-link]

![SLSA Level 2][slsa-badge]



## Table of Contents



* [Features](#features)

* [Usage](#usage)

  * [Installation](#installation)

  * [Consumption in a CLI tool](#consumption-in-a-cli-tool)

  * [Example](#example)

    * [Import](#import)

    * [Execute](#execute)

  * [API](#api)

    * [`languages` (_optional_)](#languages-optional)

    * [`vcsHosts` (_optional_)](#vcshosts-optional)

    * [`dependencyUpdaters` (_optional_)](#dependencyupdaters-optional)

* [Contributing](#contributing)

  * [Dependencies](#dependencies)

  * [Verification](#verification)

* [Related Projects](#related-projects)

* [Inspiration](#inspiration)



## Features



* configures generic editor settings through [EditorConfig](http://editorconfig.org/)

* scaffolds [license](https://spdx.org/licenses/) details

* scaffolds [VCS](https://en.wikipedia.org/wiki/VCS) details if [git](https://git-scm.com/)

  is chosen

* scaffolds the chosen [VCS](https://en.wikipedia.org/wiki/VCS) Host details

* scaffolds the chosen [CI](https://en.wikipedia.org/wiki/Continuous_integration)

  service config

* scaffolds the project `README.md`

* scaffolds language specific details by delegating to

  [provided scaffolder functions](#languages-optional)



## Usage



[![npm][npm-badge]][npm-link]

![node][node-badge]

[![MIT license][license-badge]][license-link]



### Installation



```sh

$ 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](https://github.com/travi/scaffolder-sub-command)

for [commander](https://www.npmjs.com/package/commander) is an example of such

a wrapper.



### Example



#### Import



```javascript

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

```



#### Execute



```javascript

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](https://github.com/form8ion/awesome#languages).



__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`

    * `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](https://github.com/form8ion/awesome#version-control-services).



__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](https://github.com/form8ion/awesome#dependency-update-services).



__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`



## Contributing



[![Conventional Commits][commit-convention-badge]][commit-convention-link]

[![Commitizen friendly][commitizen-badge]][commitizen-link]

[![PRs Welcome][prs-badge]][prs-link]

[![Renovate][renovate-badge]][renovate-link]

[![semantic-release: angular][semantic-release-badge]][semantic-release-link]



### Dependencies



```sh

$ nvm install

$ npm install

```



### Verification



```sh

$ npm test

```



## Related Projects



* [javascript-scaffolder](https://npm.im/@travi/javascript-scaffolder)

* [scaffolder-sub-command](https://github.com/travi/scaffolder-sub-command)

* [github-scaffolder](https://github.com/travi/github-scaffolder)

* [travis-scaffolder-javascript](https://github.com/travi/travis-scaffolder-javascript)

* [cli](https://npm.im/@travi/cli)



## Inspiration



* [Yeoman](http://yeoman.io/)

* [Lass](https://lass.js.org/)



[npm-link]: https://www.npmjs.com/package/@form8ion/project



[npm-badge]: https://img.shields.io/npm/v/@form8ion/project?logo=npm



[license-link]: LICENSE



[license-badge]: https://img.shields.io/github/license/form8ion/project.svg?logo=opensourceinitiative



[commit-convention-link]: https://conventionalcommits.org



[commit-convention-badge]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg



[commitizen-link]: http://commitizen.github.io/cz-cli/



[commitizen-badge]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg



[prs-link]: http://makeapullrequest.com



[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg



[renovate-link]: https://renovatebot.com



[renovate-badge]: https://img.shields.io/badge/renovate-enabled-brightgreen.svg?logo=renovatebot



[github-actions-ci-link]: https://github.com/form8ion/project/actions?query=workflow%3A%22Node.js+CI%22+branch%3Amaster



[github-actions-ci-badge]: https://img.shields.io/github/actions/workflow/status/form8ion/project/node-ci.yml.svg?branch=master&logo=github



[node-badge]: https://img.shields.io/node/v/@form8ion/project?logo=node.js



[coverage-link]: https://codecov.io/github/form8ion/project



[coverage-badge]: https://img.shields.io/codecov/c/github/form8ion/project?logo=codecov



[slsa-badge]: https://slsa.dev/images/gh-badge-level2.svg



[semantic-release-link]: https://github.com/semantic-release/semantic-release



[semantic-release-badge]: https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release