Wonders

A JavaScript library for building command-line applications with JSX.

NOTE: This framework is currently in its initial stage of development and is still highly experimental. Not all features have been implemented yet so please feel free to help contribute towards features, bugs, and documentations where necessary.

Install

Install via npm or yarn

$ npm i -S wonders

# or with yarn:

$ yarn add wonders

Setup

Import Wonders in your files.

import Wonders from 'wonders';

// Declare the JSX pragma
/** @jsx Wonders.Component */

Instead of declaring the JSX pragma in each file, it is recommended to install babel-preset-wonders which includes all the necessary babel presets and plugins to get you started with Wonders.

{
    "presets": ["wonders"]
}

Program Layout

A simple <program/> will consist of multiple <commands/>. These elements are handled internally by the renderer.

A simple structure would look something like this:

const App = (
    <program version="1.0.0" args={process.argv}>
        <command name="foo">Foo!</command>
        <command name="bar">Bar!</command>
        <command name="baz">Baz!</command>
    </program>
);

The example above will only render and execute the <command name="foo" />.

$ ./cli.js foo

# -> Foo!

Creating Your First Command Line Application

Wonders can render to any stream. For this example, we will be writing to process.stdout so our command-line application can work.

We will need to pass the argument list (from the user input) into the <program /> element.

#!/usr/bin/env node

// file: ./cli.js

import Wonders from 'wonders';

const App = (
    <program args={process.argv}>
        <command name="hello">
            Hello, World!
        </command>
    </program>
);

Wonders.render(<App />, process.stdout);

Running the script will result with:

$ ./cli.js hello

# -> Hello, World!

Asynchronous Actions

Wonders supports for rendering output from asynchronous task. Suppose you want to write a script that would deploy something to a remote server. A simple example can be written like so:

const deploy = () => {
    return new Promise((resolve) => {
        // perform remote server deployment
        setTimeout(() => {
            // resolve with a message once finished.
            resolve('Deployed!');
        }, 5000);
    });
};

const App = (
    <program args={process.argv}>
        <command name="deploy" onAction={deploy} />
    </program>
);

Wonders.render(<App />, process.stdout);

$ ./cli.js deploy

# .... waits 5 seconds
# -> Deployed!

Functional and Class Components

Wonders follow the same patterns as React when building reusable components for your <command/>.

The simplest way to write a component is to write a regular function.

function beep() {
    return 'Beep!';
}

Or as an ES6 class:

class Boop extends Wonders.Component {
    render() {
        return <p>Boop!</p>;
    }
}

You can feel free to compose your components and stylize your output as necessary.

import Wonders from 'wonders';

export function stylize() {
    return (
        <div>
            <p><strong>This is bold text.</strong></p>
            <p><em>This is italicized text.</em></p>
            <p><u>This is underlined text.</u></p>
        </div>
    );
}

Demo Application

See the codebase for a working demo application below:

https://github.com/vutran/wonders-demo

vutran / wonders