Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mkrl/ttty
A very simple pure JS lightweight terminal "emulator"
https://github.com/mkrl/ttty
browser cli command-line console javascript terminal typescript
Last synced: about 15 hours ago
JSON representation
A very simple pure JS lightweight terminal "emulator"
- Host: GitHub
- URL: https://github.com/mkrl/ttty
- Owner: mkrl
- License: mit
- Created: 2018-10-13T19:30:44.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-09-24T18:15:02.000Z (about 2 months ago)
- Last Synced: 2024-11-10T19:38:30.718Z (7 days ago)
- Topics: browser, cli, command-line, console, javascript, terminal, typescript
- Language: TypeScript
- Homepage: http://mkrl.xyz/ttty
- Size: 317 KB
- Stars: 57
- Watchers: 2
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ttty
A dead simple lightweight TypeScript terminal "emulator" that mimics terminal behaviour in browser.
Features:
- Tiny, dependency-free and built with modern JS
- Easy-to-add custom commands
- Events
- Command history
- Command arguments with validation
- "Foreground processes" imitation
## Usage
### With module bundler
Add the latest release with:
`npm install ttty`
or
`yarn add ttty`
Initialize the terminal in a particular DOM element with:
```js
import { initTerminal } from 'ttty'
// ...
const terminal = initTerminal({ /* settings */ })
```
### In a browser directly
```html
```
```js
ttty.initTerminal({ /* settings */ })
```
Initialize with parameters:
```js
const settings = {
host: document.querySelector("#terminal"),
prompt: "user@ttty:~$ ",
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)) }
}
}
}
initTerminal(settings)
```
## Working with the terminal
`help` - Display a list of all commands with descriptions
`command` - Execute a command. Will display "Usage: command [parameter 1 description] [parameter 2 description], etc.", when it requires arguments but is called without them.
## API
### initTerminal
| Method | Description | Parameters |
| ------------- | ------------- | ------------- |
| `init(settings)` | Initialize a terminal in a given DOM element | `settings` object. |
### terminal
An object that's being passed to every command function & returned by `initTerminal`
| Method | Description | Parameters |
|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `print(text, isCommand, scrollIntoView)` | 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, isCommand) => Promise` | Prints a text with "typing" effect. Hides and blocks user input while typing. Resolves to either `true` or `false` depending on process interruption by the user. | `text` - String, text to be printed. `speed` - integer, miliseconds. The higher the number, the slower. `isCommand` - Boolean, optional, defaults to false. Count given string as a command (displays prompt & syntax highlight) |
| `setPrompt()` | Set terminal prompt | `newPrompt` - String |
### settings object
| Parameter | Description | Default |
| ------------- | ------------- | ------------- |
| `host`: DOM element | A DOM element to initialize terminal in. | |
| `welcomeMessage`: string | A welcome message that is being printed on initialization | |
| `enableHelp`: boolean | Toggle default `help` command that lists all the available commands and their descriptions. | true |
| `prompt`: string | Terminal prompt | '$: ' |
| `historyLength`: number | A maximum amount of commands that can be stored in the terminal history | 50 |
| `history`: string[] | A default value for terminal history (can be used to preserve history across sessions) | [] |
| `commands`: object | `commands` object | |
### commands object
| Parameter | Description |
| ------------- | ------------- |
| `name`: string | Command name. |
| `description`: string | Command description, used for the default `help` command (when enabled). |
| `argDescriptions`: string array | Array 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
| Event | Description
| ------------- | ------------- |
| `onInit` | Terminal initialization |
| `onCommand` | Existing command executed |
| `onCommand404` | Non-existing command executed |
| `onProcessStart` | Process started |
| `onProcessStop` | Process stopped |
| `onProcessInterrupt` | Process interrupted with a keyboard |
Events are being dispatched by the DOM element passed on init, for example:
```
const term = document.getElementById('terminal');
term.addEventListener('onCommand', e => console.log("known command executed!"));
```
## Custom styling
You can customize the look defining custom CSS variables. If you have multiple instances, you can even have each instance in its' own style!
| Variable | Description
| ------------- | ------------- |
| `--terminal-bg-color` | Background color |
| `--terminal-fg-color` | Text color |
| `--terminal-font` | Terminal font-family |
| `--terminal-accent-color` | Accent color |
| `--terminal-error-color` | Error color |
## Browser compatibility
ttty is built and distributed with ES6 in mind (including the minified package). You can always transpile & bundle it targeting your browser set of choice.
Browsers that do not support CSS variables (IE < 11) might not be able to make use of custom themes. In order to use ttty with older browsers please rebuild this with custom properties removed.