@aofl/cli

@aofl/cli

@aofl/cli is a command line tool that provides some essential tools to help the development process of aofl-js apps. It supports scaffolding new projects and components, generating .pot files for i18n, and probably it's most useful feature is, allowing the programmers to source (clone into the project) installed node modules, update them and reinstall from npm once the updates have been merged and deployed to npm.

Installation

We prefer to install @aofl/cli at project level and use it through npm run ....

npm i -D @aofl/cli

Usage:

@aofl/cli utilizes commander and uses Git-style sub-commands.

Help

You can use the help command at program level and at command level.

program level

$ aofl --help

#  Usage: aofl [options] [command]
#
#  Options:
#
#    -V, --version          output the version number
#    -h, --help             output usage information
#
#  Commands:
#
#    init <path>            Initializes an aofl project
#    source <moduleName>    Download an npm module into your project
#    conclude <moduleName>  conclude module
#    g [type] [name]        scaffold component
#    i18n <moduleName>      Generates .pot files from source
#    dom-scope [path]       validate generated dom-scope
#    help [cmd]             display help for [cmd]
#
#  Examples:
#
#    aofl --help
#    aofl source

Command level

$ aofl help g

#  Usage: aofl-g [options]
#
#  Options:
#
#    -h, --help  output usage information
#
#  Examples:
#
#    aofl help g
#    aofl g c path/to/element-name ## generate an element that extends AoflElement
#    aofl g mixin path/to/mixin ## generate a mixin class

init

The init command is used to initialize a new aofl project. You can specify a repo or use one of the base application. It works by cloning the specified repo into the tmp folder and copying necessary files to the specified target directory and finishes with running npm install in the target directory.

Options

$ aofl init [--base base | --repo path/to/repo] [--ref branch|tag] [target]

target

Target is the location of the project we want to initialize. By default the current working directory is used. Target directory must be empty and it will be created if it doesn't exist.

base

Base refers to a starter project currently it support default and doc. If the option is omitted default will be used. Note base takes precedence over repo and will be used if both options are present.

repo

Repo can be used to initialize an application from any repo. You can create your special case starting apps and use the repo option to initialize new projects from them.

$ aofl help init

# Usage: aofl-init [options]
#
# Options:
#   --repo [repo]   repo url
#   --base [base]   starter application alias
#   --ref [branch]  Git ref to clone from. Branch, tag, ...
#   -h, --help      output usage information
#
#   Examples:
#
#     aofl help init
#     aofl init path/to/project ## generate a bare bone aofl project
#     aofl init --base doc ## generate a documentation project just like @aofl components example projects

g

Short for generate and can be used to scaffold components.

Options

aofl g [type] [name]

type

Type is always required and it denotes the type of the component. c and mixin are the two supported types. c can be used to create a component and mixin can be used to create a mixin.

name

Name can be used to specify the where we want to create the new component and it's name. The default value is the current working directory and it can be omitted.

Consider $ aofl g c js/my-component. This will create a component in the js directory relative to the current directory (./js/my-component/{index.js, template.js, index.css}). I will create js if it doesn't already exist.

The base name my-component is components tag name and also camelCased and used as the class name.

Generated ./js/my-component/index.js file...

import styles from '../styles.css';
import template from '../template';
import AoflElement from '@aofl/web-components/aofl-element';

/**
 * @summary MyComponent
 * @class MyComponent
 * @extends {AoflElement}
 */
class MyComponent extends AoflElement {
  /**
   * Creates an instance of MyComponent.
   */
  constructor() {
    super();
  }

  /**
   * @readonly
   */
  static get is() {
    return 'my-component';
  }

  /**
   *
   * @return {Object}
   */
  _render() {
    return super._render(template, [styles]);
  }
}

window.customElements.define(MyComponent.is, MyComponent);

dom-scope

This command checks the project files and reports any duplicated dom-scope attributes generated by @aofl/dom-scope-loader.

$ aofl help dom-scope

#  Usage: aofl-dom-scope [options]
#
#  Options:
#
#    -p, --pattern [pattern]        list of patterns to search. Wrap patterns in "". (default: )
#    -e, --exclude [paths]          list of paths to exclude (default: )
#    -E, --exclude-pattern [paths]  list of patterns to exclude (default: )
#    -h, --help                     output usage information

source & conclude

There's no easy way to modify installed node modules when we find bugs or need to add functionality. The source command enables us to clone an installed node module into our project as a git submodule and links it back to the node_modules folder. Hence, all our imports continue working as before.

Once we source a module we can cut a new branch, introduce our modifications and send a pull request to the maintainer. We can commit the submodule with our code and push it to the repo and even push our changes to production.

Once the pull request is accepted by the package maintainer. We can checkout the latest released version of the package in the sourced submodule and test our application. Once we can verify that we have the correct version we can use the conclude command to remove the sourced repo and install the package from npm with the correct version;

** Note: this is still an experimental feature. Make sure you understand git submodules before using this feature.

source Options

$ aofl source <module_name> [--repo path/to/repo]

module_name

Use the name of the module you want to source. module_name is a variadic option and multiple names can be used. aofl source uses the installed package's package.json file to find the path to the repo of the specified modules and will exit with an error if the repo cannot be reached.

In addition to cloning the package repo aofl source tries to match the installed version of the package to a reference (tag or branch) in the repo.

Optionally you can specify a version or a git reference as part of the module name. E.g. $ aofl source @aofl/web-components@1.0.0.

repo

Sometimes automatic sourcing of a module fails. This could be due to missing information in the package.json or the program cannot connect to the specified repo. Or we would like to clone from a forked copy of a module. The repo option allows us to specify a repo for a single module.

$ aofl source @aofl/web-components --repo [e-mail]:AgeOfLearning/aofl.git

conclude Options

$ aofl conclude <module_name> [[--all] [--revert]]

module_name

module_name can be used to conclude a module. This process takes the version specified in the sourced modules package.json and installs the package from npm with at this version.

all

The all command can be used to conclude all previously sourced modules.

revert

revert can be used in conjunction with a single module or --all. It concludes the changes and installs the version of the module before we sourced it.