Skip to content

d4rkr00t/opaline

Folders and files

NameName
Last commit message
Last commit date

Latest commit

7fb8399 · Mar 20, 2022
Mar 20, 2022
Mar 20, 2022
Apr 17, 2020
Mar 11, 2021
Mar 20, 2022
Feb 24, 2020
Apr 18, 2020
Mar 11, 2021
Mar 20, 2022
Apr 24, 2019
Apr 12, 2020
Mar 20, 2022

Repository files navigation



opaline


Opaline – CLI Tools Framework


Node.js CI

Opaline — a CLI tools framework and compiler. It draws inspiration from NextJS(and similar projects) and provides a quick, convention based, way of creating CLI tools.

  1. It looks for files in ./commands folder and treats them as commands for a CLI:

    • commands
      └── build.ts
      
      # Means it can be run as following:
      λ cli build
      
  2. Command file must export a function (can be async function too):

    • export default function myCommand() {}
      // or
      module.exports = async function myCommand() {};
  3. Uses JSDoc to describe parameters and documentation for a CLI. Read more on supported JSDoc syntax and how to use it here.

Table of Contents

Usage

Use a generator to bootstrap an Opaline based CLI:

λ npx @opaline/core create app
λ cd app
λ npm install

Compile the CLI:

λ npm run build
λ npm run dev # for dev mode with watch and auto linking

Creating Commands

By default generator creates commands/index.js file, which is a default command, and can be run without specifying a command name:

λ cli --param1 20

But if required there might be multiple commands in one CLI. In order to do that, we just need to create another file in ./commands folder (or rename index.js, it's not required to have a default command):

// ./commands/build.js

export default function build() {
  console.log("hello build!");
}

Adding Command Parameters and Documentation

Opaline uses JSDoc to define parameters and documentation for a command.

Using unnamed arguments

Opaline can pass all non-flag arguments to a command, for this command needs to define an $inputs argument in the JSDoc as shown below:

// ./commands/build.js
/**
 * Description of a command is just a comment above the command's function.
 * Params are described as JSDoc params:
 *
 * @param {Array<string>} $inputs Any non-flag arguments are passed here
 */
export default function build($inputs) {
  console.log(`hello ${name}, language ${lang}`);
}

It's also possible to define named (flag) arguments:

// ./commands/build.js

/**
 * Description of a command is just a comment above the command's function.
 * Params are described as JSDoc params:
 *
 * @param {Array<string>} $input Any non-flag arguments are passed here
 * @param {string} name Name of an app to build
 * @param {string} [lang="TypeScript"] A parameter with default value
 */
export default function build($inputs, name, lang) {
  console.log(`hello ${name}, language ${lang}`);
}

Help will be generated for both default and this new command:

λ examples-for-docs --help # help for the whole cli, with list of commands

VERSION
  examples-for-docs/0.0.0

USAGE
  examples-for-docs inputs --param1 10 --param2 20

COMMANDS
  build     Description of a command is just a comment above the command's function. Params are described as JSDoc params:

> NOTE: To view the usage information for a specific command, run 'examples-for-docs [COMMAND] --help'

OPTIONS
  --param1      Some parameter for a CLI with a default value [number] [default: 20]
  --param2      Some parameter for a CLI [string]
  --help        Output usage information
  --version     Output the version number




λ examples-for-docs build --help # help for a subcommand

Description of a command is just a comment above the command's function. Params are described as JSDoc params:

OPTIONS
  --name     Name of an app to build [string]
  --lang     A parameter with default value [string] [default: "TypeScript"]

JSDoc

Opaline uses JSDoc to describe command's parameters and documentation.

Supported JSDoc Tags

Tag Description
@paramhttps://jsdoc.app/tags-param.html Supports primitive types: string, number, boolean. And arrays of strings string[]
@example Note: only one line examples: @example {cliName} --params 10

Extra JSDoc Tags

Tag Description
@param $inputs Indicates that command receives unnamed arguments
@usage Similar to example, but outlines the main example on how to use a CLI command. @usage {cliName} build
@short Defines an alias (shortcut) for a parameter. @short name=n
{cliName} A variable that will be replaced by the name of a CLI tool described in package.json. Supported by @usage and @example

package.json

Opaline gets multiple things from a package.json file, to even more reduce configuration:

package.json#bin

https://docs.npmjs.com/files/package.json#bin

There are 2 way of using the bin field in package.json:

// 1
{
  "name": "cli-name",
  "bin": "./cli/cli.js"
}

// 2
{
  "name": "cli-name",
  "bin": {
    "cli-name": "./cli/cli.js"
  }
}

Opaline supports both of them. And uses those fields in a following way:

  1. Path to a CLI file – For both cases the file path is used as an output target for a CLI entry point, and will be automatically created by Opaline, no need to manually create it.
  2. Name of a CLI – For [1] the name will be package.json#name, if you need to have a different name than the name of a package, use an option 2. Name is used as {cliName} in JSDoc and also when linking packages in dev mode. Which makes them accessible globally, by this name:
    • cli-name [COMMAND]

package.json#description

Used as main description for a CLI tool.

Examples

Tools built with Opaline:

Screenshots