vue-command

A fully working, most feature-rich Vue.js terminal emulator. See the demo.

Features

• Parse arguments with yargs-parser
• Search history (with ↑/↓)
• White/Dark theme support
• Autocompletion resolver (with ↹)
• Supports asynchronous commands
• Customize terminal with slots

Installation

$ npm i vue-command --save

Usage

Let's start with a very simple example. We want to send "Hello world" to Stdout when entering hello-world.

<template>
  <vue-command 
    :commands="commands" 
    :executed.sync="executed" />
</template>

<script>
import VueCommand, { createStdout } from 'vue-command'
import 'vue-command/dist/vue-command.css'

export default {
  data: () =>  ({
    commands: { 
      'hello-world': () => createStdout('Hello world') 
    },

    executed: new Set()
  })
}
</script>

Now a more complex one. Let's assume we want to build the Nano editor available in many shells.

We will use the provided environment variable to make sure the editor is only visible when this command is executing and inject a function called terminate to tell the terminal that the command has been finished when the user enters Ctrl + X. Furthermore, we inject the setIsFullscreen function to switch the terminal into fullscreen mode.

<template>
  <div v-if="environment.isExecuting">
    <textarea
      ref="nano"
      @keydown.ctrl.88="terminate">This is a text editor! Press Ctrl + X to leave.</textarea>
  </div>
</template>

<script>
export default {
  inject: ['setIsFullscreen', 'terminate'],

  created () {
    this.setIsFullscreen(true)
  },

  mounted () {
    this.$refs.nano.focus()
  }
}
</script>

Now the command has to return the component. Additionally, we have to pass a Set with the sync modifier which will contain all executed programs. This property can be changed at any time.

<template>
  <vue-command 
    :commands="commands" 
    :executed.sync="executed" />
</template>

<script>
import VueCommand from 'vue-command'
import 'vue-command/dist/vue-command.css'

import NanoEditor from '@/components/NanoEditor.vue'

export default {
  components: {
    VueCommand
  },

  data: () =>  ({
    commands: { 
      nano: () => NanoEditor 
    },

    executed: new Set()
  })
}
</script>

Properties

There are two types of commands: Built-in and regular ones. In most cases regular commands are appropriate. Built-in commands provide higher flexibility, see section Built-in for more information.

Some properties can be changed by the terminal, therefore, the sync modifier has to be added.

Commands

commands must be an object containing key-value pairs where key is the command and the value is a function that will be called with the yargs arguments. The function can return a Promise and must return or resolve a Vue.js component. To return strings or nothing use one of the convenient helper methods:

Helper methods can be imported by name:

import { createStdout, createStderr, createDummyStdout } from 'vue-command'

If none of the helper methods is used, the command has to be manually terminated inside the component. Next to termination it's possible to inject the following functions to manipulate the terminal or signal an event:

Functions can be injected into your component by name:

inject: ['setIsFullscreen', 'setIsInProgress', 'terminate']

In your component you have access to a context and an environment variable. The environment variable contains the following properties (note that built-in commands have to take care by theirselves about the terminals state):

The context variable contains the following properties:

Built-in

Built-in commands provide more control over the terminals behaviour. On the other side, they have to take care about every regular command step. As a matter of fact, regular commands are just calling helper methods or change properties which could be also called or changed by built-in commands. Regular commands can be seen as a facade to built-in commands.

The API is more likely to change. The argument that is called within the built-in command is the unparsed Stdin. It's possible to use a custom parser at this place.

To fully simulate a full command circle a built-in command has to follow these steps:

1. Add the programm to the executed Set property
2. Increase the history pointer
3. Emit command executing started
4. Tell terminal there is a command in progress
5. Push the Stdout component into the history property
6. Execute actual task
7. Exit the command with the injected terminate function

Autocompletion resolver

It is possible to provide a function that is called when the user hits the ↹ key. This function needs to take care of the autocompletion experience and should make usage of properties like history and stdin. The following shows a possible, simple autocompletion function:

this.autocompletionResolver = () => {
  // Make sure only programs are autocompleted since there is no support for arguments, yet
  const command = this.stdin.split(' ')
  if (command.length > 1) {
    return
  }

  const autocompleteableProgram = command[0]
  // Collect all autocompletion candidates
  let candidates = []
  const programs = [...Object.keys(this.commands), ...Object.keys(this.builtIn)].sort()
  programs.forEach(program => {
    if (program.startsWith(autocompleteableProgram)) {
      candidates.push(program)
    }
  })

  // Autocompletion resolved into multiple results
  if (this.stdin !== '' && candidates.length > 1) {
    this.history.push({
      // Build table programmatically
      render: createElement => {
        const columns = candidates.length < 5 ? candidates.length : 4
        const rows = candidates.length < 5 ? 1 : Math.ceil(candidates.length / columns)

        let index = 0
        let table = []
        for (let i = 0; i < rows; i++) {
          let row = []
          for (let j = 0; j < columns; j++) {
            row.push(createElement('td', candidates[index]))
            index++
          }

          table.push(createElement('tr', [row]))
        }

        return createElement('table', { style: { width: '100%' } }, [table])
      }
    })
  }

  // Autocompletion resolved into one result
  if (candidates.length === 1) {
    this.stdin = candidates[0]
  }
}

Slots

Bar

It's possible to fully customize the terminal bar using slots as shown in the following. Note: If using the bar slot, the properties hide-bar and title will be ignored.

<template>
  <vue-command
    :commands="commands"
    :executed.sync="executed">
    <div slot="bar">
      Pokedex
    </div>
  </vue-command>
</template>

Prompt

Customize the prompt with the prompt slot. Note: If using the prompt slot, the property prompt will be ignored and the CSS class term-ps has to be manually applied.

<template>
  <vue-command
    :commands="commands"
    :executed.sync="executed"
    prompt="neil">
    <span
      class="term-ps" 
      slot="prompt">
      {{ prompt }} ready to take off:&nbsp;
    </span>
  </vue-command>
</template>

Events

Browser support

This library uses the ResizeObserver to track if the terminals inner height changes. You may need a pollyfill to support your target browser.

Projects using vue-command

• docker-management-dashboard - A management dashboard for your local docker containers
• saber-theme-klieh - A Saber theme mimicking a terminal
• ts-git - A naïve implementation of git, written in TypeScript
• curvy-idle-game - Short idle game where you get to pat her

Chuck Norris API

The Chuck Norris jokes are comming from this API. This library has no relation to Chuck Norris or the services provided by the API.

Author

Julian Claus and contributors. Special thanks to krmax44 for the amazing work!

License

MIT