README.md

gogen

Use stream API to scaffold projects or files.

Features

• Simple, easy to use
• Lightweight, single file bundled (<40K gzip size), no need to install globally, just run npx
• Automatically rename gitignore to .gitignore, due to npm/issues/1862
• Automatically set name field in package.json
• Automatically parse command line arguments with mri
• Add command line prompts with prompts
• Render *.t.foo (or *.foo.t) to *.foo with lodash template
• Provide fast, in-memory testing API

Usage

Run existing generator

Run from any npm package (registry/GitHub/git/folder...), same as npm install or yarn add:

# install generator to directory
npx gogen <generator> <directory>
# eg.
npx gogen [<@scope>/]<name> <directory> # npm registry
npx gogen <user>/<repo> <directory>  # GitHub
npx gogen <host>:<name>/<repo> <directory>  # git
npx gogen <folder> <directory> # folder

Examples

• Scaffold project
  • examples/basic
  • examples/with-ejs
  • examples/with-prompts
  • gogen-pkg
• npm initializer or starter kits
  • create-gogen
  • new-mina CRA-like initializer in 12 lines.

Create generator

The default directory structure, used in examples:

.
├── .gogenrc.js # optional, defaults to `lib/.gogenrc.default.js`
├── package.json
└── template
    ├── index.js
    └── package.json

Edit the .gogenrc.js file:

/**
 * @type {import('gogen').Generator}
 */
module.exports = async ({src, dest, pipeline, install, gitInit}) => {
  await pipeline(src('template/**'), dest())
  await install()
  await gitInit()
}

Run the generator:

npx gogen <your-generator> <your-project>

Create npm initializer

Add a bin file, eg. examples/create-gogen/cli.js.

const {run} = require('gogen')
run(
  [__dirname, ...process.argv.slice(2)],
  'Usage: npm init gogen <my-generator>'
)

Run the initializer:

npm init <your-initializer> <your-project>
# or: yarn create <your-initializer> <your-project>

Configuration file

.gogenrc.js:

• run(api: Object, context: Object) => void
  • api core stream and helper APIs
    • src(glob: string | string[], options: fg.Options) => Stream read files, support fast-glob options
    • dest(path?: string) => Stream write files
    • pipeline(...streams: Stream[]) => Promise pipe a series of streams
    • template(data: Object, {ext: RegExp, test: RegExp, render: Function}) => Stream render *.t or *.t.foo files with lodash template
    • packages(content: Object | Function) => Stream change package.json
    • modify(match: RegExp | Function, transform: file => file) => Stream change files
      • modify.text(match: RegExp | Function, transform: (file, text: string) => text) => Stream change text files
      • modify.json(match: RegExp | Function, transform: (file, json: Object) => json) => Stream change json files
      • modify.rename(match: RegExp | Function, transform: (file, paths: Object) => paths) => Stream rename files
    • install(deps: string[], {dev: boolean, silent: boolean}) => Promise install dependencies
    • gitInit(message: string) => Promise init git repository
    • prompts(Array | Object) => Promise see prompts
  • context generator context
    • path: string new project's path (it's also a setter)
    • name: string new project's name (it's also a setter)
    • argv: Object command line arguments, parsed by mri

Testing

Use the mock API:

• mock(generator: string, directory: string, options: Object):
  • generator path to generator
  • directory path to output
  • options
    • answers: Object inject prompt values

const {mock} = require('gogen')

it('generate correctly', async () => {
  const {files, readFile} = await mock('.', 'dist', {
    answers: {description: 'superb'},
  })
  expect(files).toMatchSnapshot()
  expect(readFile('package.json')).toMatch(/superb/)
})

Comparison with alternatives

Library	Package Phobia
gogen
sao
yeoman