Installation

ℹ Note: This documentation uses yarn for examples but you may substitute with the npm equivalents.

Per-project:

yarn add -D @hughx/component-cli

Global:

yarn global add @hughx/component-cli

Then, in your project directory, create your component directory:

mkdir -p _templates/components/#Component#/

The script outputs to src/components by default, so you’ll need to also create that directory if it doesn’t already exist. Both paths are configurable—see “Config Files”.

Usage

Component CLI assumes (and enforces) that your components are organized in a modular fashion, with each component having its own directory. Beyond that, the actual file structure, frameworks, preprocessors, etc. are up to you.

In your file names and in your code, use the template variables #component# or #Component#, and the corresponding BEM- or Pascal-cased identifiers will be filled in upon execution of component add. See also the full list of template variables.

Here is how a typical component template might look:

#Component#
├── #Component#.scss
├── #Component#.test.js
├── index.js
└── methods.js

To use the CLI, you must first build a skeleton component and place it under _templates/components/#Component#/ in your project directory. In each file, place any scaffolding work that is common across all components.

For instance, for a React component:

import React from 'react';

export default function $Component$() {
  return <div className="acme-#component#"></div>
};

(acme being a namespace to avoid collisions with third-party CSS.)

Then, when you run the CLI, it will copy all files and replace all template variables with the name you specify, e.g. add Widget would result in the following substitutions:

• function $Component$() → function Widget()
• acme-#component# → acme-widget.

Currently, the CLI only makes replacements for the following file extensions:

• .js
• .json
• .jsx
• .ts
• .tsx
• .css
• .scss
• .sass
• .less
• .styl
• .graphql
• .gql

For more detail on usage, please see the API section.

Template Variables

All hash symbols (#) can be substituted with dollar signs ($) for JavaScript compatibility.

The BEM variations can also have their delimiters escaped with a single backslash (\) for CSS compatibility.

| Variables | Description | Sample Output | | ------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- | | #Component# | Pascal Case, leading underscore for subcomponents | Widget, _WidgetSubwidget | | #COMPONENT# | Constant Case, leading underscore for subcomponents | WIDGET, _WIDGET_SUBWIDGET | | #ComponentBare# | Pascal Case, no leading underscore for subcomponents | Widget, WidgetSubwidget | | #COMPONENT_BARE# | Constant Case, no leading underscore for subcomponent | WIDGET, WIDGET_SUBWIDGET | | #ComponentShort# | Pascal Case, no parent prefix for subcomponents | Widget, Subwidget | | #COMPONENT_SHORT# | Constant Case, no parent prefix for subcomponents | WIDGET, SUBWIDGET | | #component# | BEM Case, subcomponent as element relative to parent | widget, widget__subwidget | | #component:block# | BEM Case, subcomponent as new block | widget, widget-subwidget |

Config Files

You can add a .component-cli.js file to the root of your project to override default behavior. It takes the following form. Paths should be relative to the working directory in which you are calling component-cli, usually the project root.

export const config = {
  "templateDirectory": "_templates/components",
  "componentDirectory": "src/components"
};

API

See the GitHub README for details.