Installation

Project Goals

The goal of the project is to create a beautiful and extensible experience for command-line interface users, built on open web standards. In the beginning, our focus will be primarily around speed, stability and the development of the correct API for extension authors.

In the future, we anticipate the community will come up with innovative additions to enhance what could be the simplest, most powerful and well-tested interface for productivity.

Extensions

Extensions are available on npm. We encourage everyone to include hyper in the keywordsfield in package.json.

$ npm search hyper

Then edit .hyper.js and add it to plugins

module.exports = {

  config: { /*... */ },

  plugins: [
    "hyperpower"
  ]

};

Hyper will show a notification when your modules are installed to .hyper_plugins.

Keymaps

All command keys can be changed. In order to change them, edit .hyper.js and add your desired change to keymaps.

Then Hyper will change the default with your custom change.

Example: 'window:devtools': 'Cmd+Alt+O'

module.exports = {
  config: { /*... */ },

  keymaps: {
    'window:devtools': 'cmd+alt+o'
  }

};

Default keymaps:

Configuration

Config location

Note: config at ~/.hyper.js still supported, but will be ignored, if config in application directory present. Otherwise it will be moved to the application directory at first run.

The config object seen above in .hyper.js admits the following

Extensions API

Extensions are universal Node.js modules loaded by both Electron and the renderer process.

The extension system is designed around composition of the APIs we use to build the terminal: React components and Redux actions.

Instead of exposing a custom API method or parameter for every possible customization point, we allow you to intercept and compose every bit of functionality!

The only knowledge that is therefore required to successfully extend Hyper is that of its underlying open source libraries.

You can find additional details about plugin development here

Your module has to expose at least one of these methods:

Module loading

The user can hot-load and hot-reload plugins by pressing Command + R (refresh). Please strive to make plugins that don't require a complete restart of the application to work.

Notice

Plugins affecting the `BrowserWindow` will the effect on new windows after hot-reload.

In the future we might do this automatically.

When developing, you can add your plugin to .hyper_plugins/local and then specify it under the localPlugins array in .hyper.js. We load new plugins:

• Periodically (every few hours)
• When changes are made to the configuration file (plugins or localPlugins)
• When the user clicks Plugins > Update all now

The process of reloading involves

• Running npm prune and npm install in .hyper_plugins.
• Pruning the require.cache in both electron and the renderer process
• Invoking on* methods on the existing instances and re-rendering components with the fresh decorations in place.

Plugins location

Note: plugins at ~/.hyper_plugins still supported, but will be ignored, if plugins in application directory present. Otherwise they will be moved to the application directory at first run.

Note: on the main process, plugins are registered as soon as possible (we fire onLoad). On the browser, it's up to the user to trigger their load by pressing command+R. We put the user in control of the loading in this way to prevent them from losing critical work by extensions that reset state or don't preserve it correctly.

Decorating components

We give you the ability to provide a higher order component for every piece of the Hyper UI.
Its structure is as follows:

<Hyper>
  <Header>
    <Tabs>
      <Tab /> ...
    </Tabs>
  </Header>
  <Terms>
    <TermGroup>
      <SplitPane>
        <TermGroup>
          <Term /> ...
        </TermGroup>
        <TermGroup>
          <Term /> ...
        </TermGroup>
      </SplitPane>
    </TermGroup>
  </Terms>
  <Notifications>
    <Notification /> ...
  </Notifications>
</Hyper>

All the decorate* methods receive the following references in an object passed as the second parameter:

All the components accept the following two properties to extend their markup:

Your higher order component can supply a onDecoratedproperty to the decorated component to get a reference to its instance.

Your Term higher order component can supply an onCursorMovehandler property that be called when cursor has moved with an object parameter representing its relative position to Term origin:

We encourage you to maintain compatibility with other decorators. Since many can be set, don't assume that yours is the only one.

For example, if you're passing children, compose potential existing values:

render () {
  const customChildren = Array.from(this.props.customChildren)
    .concat(<p>My new child</p>);
  return <Tab {...this.props} customChildren={customChildren} />
}

Or if you use onDecorated property

onDecorated (term) {
  this.term = term;
  if (this.props.onDecorated) {
    this.props.onDecorated(term);
  }
}

Actions and Effects

All the Redux actions are available for you to handle through your middleware and reducers. For an example, refer to the Hyperpower reference plugin.

Side effects occur in two fundamental forms:

• Some actions dispatch other actions based on state.
• Some actions do async work by communicating over the RPC channel to the main process

In all cases, the side effect is passed as the effect key in the action and later handled by our middleware.

This means that you can override, compose or completely eliminate effects! In other words, this is how you can change the default functionality or behavior of the app.

As an example, consider the action we use to increase the font size when you press Command+=:

export function increaseFontSize () {
  return (dispatch, getState) => {
    dispatch({
      type: UI_FONT_SIZE_INCR,
      effect () {
        const state = getState();
        const old = state.ui.fontSizeOverride || state.ui.fontSize;
        const value = old + 1;
        dispatch({
          type: UI_FONT_SIZE_SET,
          value
        });
      }
    });
  };
}

The underlying terminal

Hyper achieves a lot of its speed and functionality thanks to the power of xterm.js

Additional APIs

The Electron app objects are extended with the following properties:

Electron BrowserWindow objects are extended with the following parameters:

Renderer windows are similarly extended with:

The rpc object is symmetrical between browser and renderer process. The API is the same as Node.js, with the exception that it only admits a single object as its parameters only:

window.rpc.emit('hi there', {
  some: 'payload',
  any: [
    'object',
    'here'
  ]
});

Example theme: Hyperyellow

The following extension simply alters the config to add CSS and yellow colors! Here's the code.

Themes are simply plugins! Only one hook, decorateConfigis needed:

exports.decorateConfig = (config) => {
  return Object.assign({}, config, {
    borderColor: 'yellow',
    cursorColor: 'yellow',
    css: `
      ${config.css || ''}
      .tabs_nav .tabs_list .tab_text {
        color: yellow;
      }
      .tabs_nav .tabs_title {
        color: yellow;
      }
    `
  });
}

I grabbed the class names by inspecting the term with Devtools, which you can trigger from View -> Toggle Developer Tools. When you do so, notice that some classes are automatically generated and followed by a random nonce (e.g.: term_13hv8io). Ignore those: they change with every new window!

Notice the emphasis on playing nice with other extensions. Specifically, we create a new object, extend only the keys we are interested in, and we compose the CSS to preserve the user's setting and that of other authors':

return Object.assign({}, config, {
  css: `
    ${config.css || ''}
    /* your css here */
  `
});

Example extension: Hyperpower

The following extension renders particles as the caret moves:

Let's walk through its code.
First, we intercept the Redux action SESSION_ADD_DATA. See the whole list of them here.

exports.middleware = (store) => (next) => (action) => {
  if ('SESSION_ADD_DATA' === action.type) {
    const { data } = action;
    if (/bash: wow: command not found/.test(data)) {
      store.dispatch({
        type: 'WOW_MODE_TOGGLE'
      });
    } else {
      next(action);
    }
  } else {
    next(action);
  }
};

Notice that we don't re-dispatch the action, which means we never render the output of the command to the terminal. Instead, we dispatch an action of our own, which we grab in the uiReducerand later map:

exports.reduceUI = (state, action) => {
  switch (action.type) {
    case 'WOW_MODE_TOGGLE':
      return state.set('wowMode', !state.wowMode);
  }
  return state;
};

exports.mapTermsState = (state, map) => {
  return Object.assign(map, {
    wowMode: state.ui.wowMode
  });
};

We then want to decorate the <Term> component so that we can access the underlying caret.

However, <Term> is not a container that we can map props to. So we use getTermProps to pass the property further down:

exports.getTermProps = (uid, parentProps, props) => {
  return Object.assign(props, {
    wowMode: parentProps.wowMode
  });
}

The extension then returns a higher order component to wrap <Term>. Notice we pass the onDecoratedproperty to access the base Term component and its DOM ref, and the onCursorMove property to use Hyper cursor API:

render () {
  return React.createElement(Term, Object.assign({}, this.props, {
    onDecorated: this._onDecorated
,    onCursorMove: this._onCursorMove
  }));
}