Emulating A Shell Environment With The ttty.js Library

Preview:

Description:

ttty.js is a tiny yet customizable terminal emulator written in TypeScript.

It provides an easy way to embed a terminal in your web app, where your users can execute tasks or commands you pre-defined.

How to use it:

1. Install and import the ttty.js.

# Yarn
$ yarn add ttty
# NPM
$ npm i ttty

import { initTerminal } from 'ttty'

2. Or insert the following files into your 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. Initialize the terminal emulator.

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

5. Customize the bash prompt. Default: ‘$:’.

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 CSSScript.com. Type Help to get started.",
})

7. Create your own commands. Default commands:

• help: Display all commands.
• command: Execute a command

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
  welcomeMessage: "Welcome to CSSScript.com. 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. Default: true.

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

9. Determine the maximum number of commands that should be stored in the terminal. Default: 50.

ttty.initTerminal({
  host: document.querySelector("#terminal"),
  prompt: "user@ttty:~$ ",
  welcomeMessage: "Welcome to CSSScript.com. 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);
// set terminal prompt
myTerminal.setPrompt(prompt);

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!"));

Changelog:

v1.6.0 (07/23/2023)

• promise-based type() API that now supports treating text as a command

v1.5.0 (07/21/2023)

• add an ability to initialize with custom history

v1.4.0 (07/16/2023)

• make TerminalEvent available to import externally

v1.3.0 (07/16/2023)

• add setPrompt to the terminal API

v1.2.0 (10/28/2021)

• add support for long argument strings

v1.1.0 (10/27/2021)

• css: bundle CSS with JS and support themes

v1.0.3 (10/26/2021)

• Bug Fixes