Home

Awesome

<h3 align="center"> <img src="https://raw.githubusercontent.com/jondot/hygen/master/media/hygen.png" alt="hygen logo" width=400 /> </h3>

build status npm version

hygen is the simple, fast, and scalable code generator that lives in your project.

<div align="center"> <img src="https://raw.githubusercontent.com/jondot/hygen/master/media/hygen.gif" width=600/> </div>

Features

New in hygen v4.0.0: a positional NAME parameter. Now you can use $ hygen component new MyComponent instead of $ hygen component new --name MyComponent.

Used By

<Image alt="Wix" height="32" src="https://upload.wikimedia.org/wikipedia/en/7/76/Wix.com_website_logo.svg"/>     <Image alt="Airbnb" height="50" src="https://upload.wikimedia.org/wikipedia/commons/thumb/6/69/Airbnb_Logo_B%C3%A9lo.svg/512px-Airbnb_Logo_B%C3%A9lo.svg.png"/>     <Image alt="Mercedes Benz AG" height="60" src="https://upload.wikimedia.org/wikipedia/commons/thumb/9/9e/Mercedes-Benz_Logo_2010.svg/320px-Mercedes-Benz_Logo_2010.svg.png"/>     <Image alt="Open Data Institute" height="60" src="https://luminategroup.com/storage/538/c/opendatainstitute%28ODI%29-logo%402x-logo.png"/>     <Image alt="Ableneo" height="80" src="https://www.ableneo.com/web/images/logo.svg"/>   <Image alt="City of Amsterdam" height="70" src="https://avatars3.githubusercontent.com/u/14022058?s=200&v=4"/>     <Image alt="Accenture" height="80" src="https://upload.wikimedia.org/wikipedia/commons/thumb/c/cd/Accenture.svg/512px-Accenture.svg.png"/>   <Image alt="Birdie" height="60" src="https://assets.website-files.com/5d07a11d8195605723dbff07/5d09430b3d6e1c5d28a6e2b6_global%E2%80%94birdie_logo_black.svg"/>     <Image alt="Kind" height="80" src="https://madebykind.com/dist/images/logos/site-logo-green-e0e983ec46.svg"/>     <Image alt="Ackee" height="80" src="https://avatars3.githubusercontent.com/u/1728223?s=400&v=4"/>   <Image alt="Aerian Studios" height="80" src="https://www.aerian.com/img/c/aerian-logo.svg"/>  <Image alt="Food and Agriculture Organization of the UN" height="100" src="https://avatars2.githubusercontent.com/u/38506195?s=200&v=4"/> <Image alt="Cape Cod Commision" height="70" src="http://www.capecodcommission.org/gfx/home-logo.jpg"/>   <Image alt="Tweak Things" height="80" src="https://avatars3.githubusercontent.com/u/49718812?s=400&v=4"/>     <Image alt="Crema" height="40" src="https://assets.website-files.com/5b6b50e79e9b6f5948395973/5d88f52b42420350d3e117d2_Asset%201.png"/>     <Image alt="Cureon" height="120" src="http://cureon.de/resources/cureon_logo.png"/>     <Image alt="Astrocoders" height="50" src="https://d33wubrfki0l68.cloudfront.net/b8f71088a0c9bc92d67476a361f35690d157d0e5/517c2/static/logo-c5d890fb431b53a7c61800feccd65ac2.png"/>     <Image alt="Vega/IDL" height="60" src="http://vega.github.io/images/idl-logo.png"/>   <Image alt="Sporty Spots" height="60" src="https://www.sportyspots.com/static/sportyspots.svg"/>    <Image alt="Thrashplay" height="50" src="https://avatars1.githubusercontent.com/u/55868193?s=200&v=4"/>   <Image alt="8base" height="80" src="https://avatars1.githubusercontent.com/u/28789399?s=200&v=4"/>    <Image alt="Instamotionh" height="50" src="https://avatars1.githubusercontent.com/u/44466967?s=200&v=4"/> <Image alt="Biotope" height="90" src="https://avatars1.githubusercontent.com/u/34653144?s=400&v=4"/> <Image alt="Frontend Labs" height="50" src="https://avatars1.githubusercontent.com/u/6691550?s=200&v=4"/> <Image alt="Swydo" height="90" src="https://avatars1.githubusercontent.com/u/1563883?s=400&v=4"/> <Image alt="Gridsome" height="70" src="https://avatars0.githubusercontent.com/u/17981963?s=200&v=4"/> <Image alt="Rosem Laboratory" height="90" src="https://avatars2.githubusercontent.com/u/22129460?s=200&v=4"/><Image alt="Sheffield Hallam University" height="70" src="https://avatars1.githubusercontent.com/u/46559136?s=400&v=4"/> <Image alt="Hackoregon" height="80" src="https://avatars3.githubusercontent.com/u/6343574?s=400&v=4"/> <Image alt="Chilly Design" height="50" src="https://avatars1.githubusercontent.com/u/13002395?s=200&v=4"/>

<Image alt="Scale Leap" height="50" src="https://avatars3.githubusercontent.com/u/41709180?s=200&v=4"/> <Image alt="Chat Logs" height="50" src="https://avatars1.githubusercontent.com/u/37252774?s=200&v=4"/> <Image alt="Stelace" height="70" src="https://avatars1.githubusercontent.com/u/32740360?s=400&v=4"/> <Image alt="Echobind." height="70" src="https://avatars0.githubusercontent.com/u/570840?s=200&v=4"/>

Quick Start

Hygen can be used to supercharge your workflow with Redux, React Native, Express and more, by allowing you avoid manual work and generate, add, inject and perform custom operations on your codebase.

If you're on macOS and have Homebrew:

$ brew tap jondot/tap
$ brew install hygen

If you have node.js installed, you can install globally with npm (or Yarn):

$ npm i -g hygen

If you like a no-strings-attached approach, you can use npx without installing globally:

$ npx hygen ...

For other platforms, see releases.

Initialize hygen in your project (do this once per project):

$ cd your-project
$ hygen init self

Build your first generator, called mygen:

$ hygen generator new mygen

Loaded templates: _templates
       added: _templates/mygen/new/hello.ejs.t

Now you can use it:

$ hygen mygen new

Loaded templates: _templates
       added: app/hello.js

You've generated content into the current working directory in app/. To see how the generator is built, look at _templates (which you should check-in to your project from now on, by the way).

You can build a generator that uses an interactive prompt to fill in a variable:

$ hygen generator with-prompt mygen

Loaded templates: _templates
       added: _templates/mygen/with-prompt/hello.ejs.t
       added: _templates/mygen/with-prompt/prompt.js

Done! Now let's use mygen:

$ hygen mygen with-prompt
? What's your message? hello

Loaded templates: _templates
       added: app/hello.js

Use a template repo

Want to start from a repo?

$ hygen init repo antfu/vitesse --to my-folder

Want to start from an existing repo on an existing project?

$ mkdir your-project && cd your-project
$ hygen init repo antfu/vitesse

What's Next?

Go to the documentation to get to know the rest of Hygen and generators.

If you're in a hurry:

A Different Kind of a Generator

hygen is a scalable generator. It has developer and team ergonomics as first priority.

It avoids "blessed" or dedicated projects that codifies code generation, which before you know it, become a product you build, needs testing, CI, separate pull request reviews, and ultimately sucks up your time and becomes this super hated thing no one likes to touch anymore.

Plus, since they are not the product you are building they become notoriously hard to reason about.

Scratch Your Own Itch

Because hygen templates live in your project, it cuts the time from having an itch for generating code (Redux, anyone?) in your current project to code generated with it and others benefiting from it.

Template Locality

hygen picks up a local _templates folder at any folder level of your project you're working from.

This is important because:

And yet, if you don't like project-local templates:

Folder Structure is Command Structure

The templates folder structure maps directly to the command structure:

$ hygen worker new jobrunner

For this command, hygen worker new maps to _templates/worker/new and all files within worker/new are rendered.

Template parameters are given with --flag VALUE, as many as you'd like. In this example we've set a parameter named name to the value jobrunner.

Subcommands

A subcommand is a file inside a your folder structure. So if the structure is this:

_templates/
    worker/
      new/
        index.html.ejs
        setup.html.ejs

And you only want setup, you can run:

$ hygen worker new:setup

You can also use the subcommand as a regular expression so, these will do the same:

$ hygen worker new:se
$ hygen worker new:se.*

Frontmatter for Decluttering

Here's how a template looks like (in our example, index.ejs.t). Templates bodies are ejs:

---
to: app/workers/<%=name%>.js
---

class <%= h.capitalize(name) %> {
    work(){
        // your code here!
    }
}

The first part of the template is a front matter, idea borrowed from Markdown, this is the metadata part of a hygen template and is part of the reason of why your templates will feel more lightweight and flexible.

All frontmatter metadata are also run through the template engine so feel free to use variables in the frontmatter as you wish.

There's one required metadata variable: to. to points to where this file will be placed (folders are created as needed).

Case changing

hygen provides ability to semantic case changing with change-case library, it's simple to use and very easy to understand.

There is a usecase for react based components generation:

---
to: components/<%= name %>/index.jsx
---
import React from 'react'

export const <%= name %> = ({ children }) => (
  <div className="<%= h.changeCase.paramCase(name) %>">{children}</div>"
)

With name HelloWorld will be compiled to:

import React from 'react'

export const HelloWorld = ({ children }) => (
  <div className="hello-world">{children}</div>"
)

You can see the full list here.

Addition, Injection, and More

By default templates are 'added' to your project as a new target file, but you can also choose to inject a template into an existing target file.

For this to work, you need to use inject: true with the accompanied inject-specific props.

---
to: package.json
inject: true
after: dependencies
skip_if: react-native-fs
---
"react-native-fs":"*",

This template will add the react-native-fs dependency into a package.json file, but it will not add it twice (see skip_if).

Here are the available mutually-exclusive options for where to inject at:

You can guard against double injection:

Also you can insert or remove empty line to injection body. That feature very useful if your editor or formatter automatically insert blank line at the end of file on save:

Build Your Own

hygen is highly embeddable. You should be able to use it by simply listing it as a dependency and having this kind of workflow in your binary.

const { runner } = require('hygen')
const Logger = require('hygen/dist/logger')
const path = require('path')
const defaultTemplates = path.join(__dirname, 'templates')

runner(process.argv.slice(2), {
  templates: defaultTemplates,
  cwd: process.cwd(),
  logger: new Logger.default(console.log.bind(console)),
  createPrompter: () => require('enquirer'),
  exec: (action, body) => {
    const opts = body && body.length > 0 ? { input: body } : {}
    return require('execa').shell(action, opts)
  },
  debug: !!process.env.DEBUG
})

Development

The Hygen codebase has a functional style where possible. This is because naturally, it feeds parameters and spits out files. Try to keep it that way.

Running hygen locally, rigged to your current codebase (note the additional -- to allow passing flags)

$ yarn hygen -- mailer new foobar

Running tests in watch mode:

$ yarn watch

Metaverse Testing

The easiest way to make an impact is to use the built-in metaverse tests suite, and then add the tests here.

The idea here is to copy templates from any project that use hygen and to test that it works at all times. This keeps tabs on the hygen universe / ecosystem (nicknamed metaverse) and makes sure this test suite breaks before hygen clients break.

Internal Testing

Start Up Speed Testing

Many generators become painfully slow to use as the thing you want to generate grow (because, real life),

This is why hygen takes speed as a first class citizen, and sports a dedicated start-up timing suite:

$ yarn test:require

In addition, thought is given to which dependencies to take in, how their file structure fan out and what kind of disk access (due to require) would hygen ultimately have when we run it. This is recorded with every test run.

Bundling a single file was evaluated (and the infrastructure is still there, using webpack) and wasn't faster than what we have right now.

Contributing

Fork, implement, add tests, pull request, get my everlasting thanks and a respectable place here :).

Thanks:

To all Contributors - you make this happen, thanks!

Copyright

Copyright (c) 2018 Dotan Nahum @jondot. See LICENSE for further details.