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 via npm or yarn

$ npm i -S wonders

# or with yarn:

$ yarn add wonders

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"]
}

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!

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!

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!

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>
    );
}

See the codebase for a working demo application below:

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

MIT © Vu Tran