Skip to content

Latest commit

 

History

History
406 lines (289 loc) · 8.89 KB

README.md

File metadata and controls

406 lines (289 loc) · 8.89 KB
Raw

Hendrix

Build status

Simple, Rails-like CLI tool for generating files quickly.

Version 1 documentation

Table of contents

Installation

Option 1: Install globally

yarn global add hendrix

or

npm install --global hendrix

Then you can run hendrix (or h) anywhere in your terminal. This is recommended when working on projects without a team.

Option 2: Local project

In local project as dev dependency

yarn add --save-dev hendrix

or

npm install --save-dev hendrix

Then you can can run yarn hendrix or npm run hendrix from your project directory. This is recommended for projects with a team so that the version of hendrix is always the same for each user.

Option 3: Without installing

npx hendrix <template> <name> <output-path> [...variables]

This is recommended for trying out Hendrix before installing.

Overview

Creating generators

Hendrix uses the following folder/file structure for generators.

generators-folder/
  template-name-folder/
    ...template-files

By default, Hendrix will search for your generators in a folder called hendrix in your project's root directory.

The directory name can be changed in the configuration.

For example, with the following structure:

hendrix/
  reactClass/
    index.js.mustache
    index.spec.js.mustache
    index.scss.mustache
    README.md.mustache

  reactClassWithVariables/
    index.js.mustache
    index.spec.js.mustache
    index.scss.mustache
    README.md.mustache

You'll have access to the following generators:

  • reactClass
  • reactClassWithVariables

That will generate the following files when called:

  • index.js
  • index.spec.js
  • index.scss
  • README.md

Passing custom variables

You can pass in custom variables using flags. You can have as many flags as you want and the value of them will be inserted directly into your template when you run the generator.

hendrix reactClass Person src/ --greeting hello

Inserts the following variables into your template:

{
  name: 'Person', 
  greeting: 'hello'
}

You can also use the flag with a single hyphen, like this:

hendrix reactClass Person src/ -greeting world

And it'll insert the variable into your template the same way:

{
  name: 'Person', 
  greeting: 'world'
}

Important: make sure to wrap strings with spaces inside of quotes:

hendrix reactClass Person src/ --greeting 'Hello, world!'
{
  name: 'Person', 
  greeting: 'Hello, world!'
}

Passing Rails-like variables

The special Rails-like variables are passed in as an array of objects with the property variables, and use the format name:value in the CLI.

You can pass as many of these variables as you like.

For example:

hendrix reactClass Person src/ firstName:string age:number

Note: no flag is used!

Will pass the following values into your template under the name variables:

{
  name: 'Person', 
  variables: [
    { name: 'firstName', value: 'string' },
    { name: 'age', value: 'number' }
  ]
}

Customizing the file name

You can pass in a custom file name using the fileName flag.

hendrix reactClass Person src/ --fileName hello

Which will output (based on the default reactClass generator):

src/
  Person/
    hello.js
    hello.spec.js
    hello.scss
    hello.md

Getting started

Creating generators

Running the help command for the first time without any defined generators will create a new folder called hendrix with two generator examples called reactClass and reactClassWithVariables.

The example generators will have .mustache files and require no additional setup.

Other template engines can be used, such as Pug, Haml, etc. by adding a custom renderTemplate function in the configuration. See the recipes section for examples using the most popular template engines.

hendrix --help

As expected, the help command will also print out instructions on how to use Hendrix.

To run any Hendrix command, you can use either h or hendrix. We'll use hendrix in all of our examples, but feel free to use whatever version you prefer.

After running the help command for the first time, you'll see a message saying some example generators were created.

You should see something like this in your terminal:

Available generators:
  reactClass
  reactClassWithVariables

Configuration

Hendrix accepts a .hendrixrc.js config file in the root directory of your project with the following properties:

interface HendrixConfig {
  // path of your generators directory
  generatorsPath?: string;

  // base paths for your generated files to go into
  outputPaths?: { [templateName: string]: string };

  // hook for calling a function after the help message is called
  // useful for adding extra information to the help message
  onPostHelp?: () => void

  // custom template render function
  // so you can use other engines like Handlebars, EJS, etc.
  renderTemplate?: (template, {[variableName: string]: any}) => string
}

// default configuration
const { render } = require('mustache');

const config = {
  generatorsPath: "hendrix",
  outputPaths: {},
  onPostHelp: () => {} /* noop */,
  renderTemplate: (template, variables) => render(template, variables)
};

module.exports = config;

Recipes

Custom generators directory

// .hendrixrc.js

module.exports = {
  generatorsPath: "my-custom-generators-folder"
};

Looks for generators in ./my-custom-generators-folder/ instead of ./hendrix.

Custom output paths

// .hendrixrc.js

module.exports = {
  outputPaths: {
    view: "src/views",
    helper: "src/helpers"
  }
};

Will now create files from the view generator starting from src/views/, i.e. to generate files in src/views/home you can now run:

hendrix view Home home

Note: the path in the command is just home, and not src/views/home.

Or similarly, to generate files in src/helpers/home you can now run:

hendrix helper home home

Note: as in the previous command, the path is just home, and not src/helpers/home with this configuration.

Adding additional text to help message

// .hendrixrc.js

module.exports = {
  onPostHelp: () => console.log('Some extra help message information!')
};

Outputs "Some extra help message information!" at the bottom of the default help message when running hendrix --help.

Custom template engines

Any template engine that takes in a string of the template and an object of variables can be used, which should be all of them :)

Handlebars
// .hendrixrc.js
const { compile } = require('handlebars');

module.exports = {
  renderTemplate: (templateFileContent, context) => compile(templateFileContent)(context)
};
EJS
// .hendrixrc.js
const { compile } = require('ejs');

module.exports = {
  renderTemplate: (templateFileContent, context) => compile(templateFileContent)(context)
};
Pug
// .hendrixrc.js
const { render } = require('pug');

module.exports = {
  renderTemplate: (templateFileContent, context) => render(templateFileContent, context)
};
Hogan
// .hendrixrc.js
const hogan = require('hogan.js');

module.exports = {
  renderTemplate: (templateFileContent, context) => hogan.compile(templateFileContent).render(context)
};
Nunjucks
// .hendrixrc.js
const { renderString } = require('nunjucks');

module.exports = {
  renderTemplate: (templateFileContent, context) => renderString(templateFileContent, context)
};

Contributing

Contributions are welcome! Create an issue and let's talk!

License

MIT