Press "Enter" to skip to content

Pure Simple and Lightweight JS Terminal Emulator | ttty.js

ttty.js is a simple and lightweight Terminal emulator‘ of TypeScript which emulates the terminal behavior of the browser.

Featuring:

  • Tiny, dependency-free and built with modern JS
  • Easy-to-add custom commands
  • Events
  • Command history
  • A help message
  • Command arguments with validation
  • Interruptable “foreground process” imitation
  • Small but powerful API

Browser compatibility

ttty was designed and distributed with ES6 in mind (including the mini-package). You can always convert and aggregate them to target the browser set of your choice.

How to make use of it:

1. Install and import the ttty.js file.

# Yarn
$ yarn add ttty

# NPM
$ npm i ttty
import { initTerminal } from 'ttty'

2. Or, insert the following files into the document.

<link rel="stylesheet" href="ttty.css" />
<script src="ttty.iife.js"></script>

3. Create an empty container for the terminal.

<div id="terminal"></div>

4. Configure the terminal emulator.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
})

5. Customize the bash prompt.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
})

6. Customize the help message.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
  welcomeMessage: "Welcome to WCF. Type Help to get started.",
})

7. Create your own commands.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
  welcomeMessage: "Welcome to WCF. Type Help to get started.",
  commands: {
    echo: {
      name: "echo",
      description: "a test command with one echo arg",
      argDescriptions: ["a string to be echoed in console"],
      func: ({ print }, argument) => { print(argument) }
    },
    test: {
      name: "test",
      description: "a test command with no args",
      func: ({ print }) => { print("foo") }
    },
    multiply: {
      name: "multiply",
      description: "Multiply two numbers",
      argDescriptions: ["number one", "number two"],
      func: ({ print }, one, two) => { print(Number(one) * Number(two)) }
    }
  }
})

8. Enable/disable the help command.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
  welcomeMessage: "Welcome to WCF. Type Help to get started.",
  enableHelp: false,
})

9. Determining the maximum number of commands that should be stored in the device.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
  welcomeMessage: "Welcome to WCF. Type Help to get started.",
  historyLength: 10,
})

10. API methods.

// print text
myTerminal.print(text, isCommand);

// emulate a command execution
myTerminal.run(text);

// start a "foreground process"
myTerminal.start();
myTerminal.stop();

// print text with a "typing" effect
myTerminal.type(text, speed, callback);

11. Events.

const myTerminal = document.getElementById('terminal');

term.addEventListener('onInit', e => console.log("Initialized!"));

term.addEventListener('onCommand', e => console.log("Executed!"));

term.addEventListener('onCommand404', e => console.log("Non-existing command executed!"));

term.addEventListener('onProcessStart', e => console.log("Process started!"));

term.addEventListener('onProcessStop', e => console.log("Process stopped!"));

term.addEventListener('onProcessInterrupt', e => console.log("Process interrupted with a keyboard!"));

API

initTerminal

MethodDescriptionParameters
init(settings)Initialize a terminal in a given DOM elementsettings object.

Terminal

An object that’s being passed to every command function & returned by initTerminal

MethodDescriptionParameters
print(text, isCommand)Prints a given text in the terminal (accepts raw HTML)text – String, isCommand – Boolean, optional, defaults to false. Count given string as a command (displays prompt & syntax highlight)
run(text)Emulates a command execution in a terminal (acts the same way as a user would have typed and pressed Enter)text – String
start()Starts a “foreground process”: user input is blocked and command prompt never appears. 
stop()Stops “foreground process”. 
type(text, speed, callback)Prints a text with “typing” effect. Hides and blocks user input while typing.text – String, text to be printed. speed – integer, miliseconds. The higher the number, the slower. callback – function, gets executed when the process is finished.

Settings Object

ParameterDescriptionDefault
host: DOM elementA DOM element to initialize terminal in. 
welcomeMessage: stringA welcome message that is being printed on initialization 
enableHelp: booleanToggle default help command that lists all the available commands and their descriptions.true
prompt: stringTerminal prompt‘$: ‘
historyLength: numberA maximum amount of commands that can be stored in the terminal history50
commands: objectcommands object 

Commands Object

ParameterDescription
name: stringCommand name.
description: stringCommand description, used for the default help command (when enabled).
argDescriptions: string arrayArray of strings that describe command line arguments in order of appearance.
func: function(terminal, …arguments)Function. Accepts an array of parameters in order of appearance (i.e. function(terminal, one, two) will correspond to two arguments passed as command one two)

Events

EventDescription
onInitTerminal initialization
onCommandExisting command executed
onCommand404Non-existing command executed
onProcessStartProcess started
onProcessStopProcess stopped
onProcessInterruptProcess interrupted with a keyboard

Emulating A Shell Environment, ttty.js Plugin/Github


See Demo And Download

Official Website(mkrl): Click Here

This superior jQuery/javascript plugin is developed by mkrl. For extra Advanced Usages, please go to the official website.

Be First to Comment

    Leave a Reply

    Your email address will not be published. Required fields are marked *