Commands

The Terminal component supports customized commands for the user to interact with the terminal. The commands are defined in the commands property of the Terminal component. The commands property is an array of Commands, where each object represents a command.

import {
  Command,
  Terminal,
  TerminalInputBox,
  TerminalLoader,
  TerminalOutput,
  TerminalTitleBar,
  TerminalWelcomeMessage,
} from '@envoy1084/react-terminal';
 
const MyComponent = () => {
  const commands: Command[] = [
    {
      name: 'time',
      description: 'Display the current time',
      handler: () => {
        return new Date().toLocaleTimeString();
      },
    },
    {
      name: 'fetch',
      description: 'Fetch from the url',
      args: ['url'],
      handler: async (args) => {
        const url = args.shift() ?? '';
        const res = await fetch(url);
        const json = await res.json();
        return JSON.stringify(json, null, 2);
      },
    },
  ];
  return (
    <Terminal commands={commands}>
      <TerminalTitleBar>
        <TerminalTitleBar.ActionGroup />
        <TerminalTitleBar.Title />
      </TerminalTitleBar>
      <TerminalWelcomeMessage />
      <TerminalOutput />
      <TerminalInputBox>
        <TerminalInputBox.Prompt />
        <TerminalInputBox.TextArea />
      </TerminalInputBox>
      <TerminalLoader />
    </Terminal>
  );
};
 
export default MyComponent;

Command

Each command object has the following properties:

• name: string - The name of the command.
• description: string? - The description of the command.
• usage: string? - The usage instructions for the command.
• args: string[]? - The arguments required by the command.
• waitForExecution: boolean? - Specifies whether the command should wait for execution to complete before returning. Defaults to false.
• handler: CommandHandler - The handler function that is called when the command is executed.
• onError: CommandHandler? - The error handler function that is called when an error occurs during command execution. If not provided, the error will be logged to the Terminal.
• callback: () => void | Promise<void>? - The callback function that is called after the command is executed. This function is called regardless of whether the command was successful or not.

Command Handler

The CommandHandler function is called with the following arguments:

• args: string[] - The command arguments.
• text: string - The value of the terminal input.
• command: Command - The command being executed

The CommandHandler function should return a TerminalOutputValue object. The TerminalOutputValue object can be one of the following:

• undefined - If the command does not return any output.
• string - If the command returns a string output.
• { html: JSX.Element } - If the command returns a JSX element output.

Command Error Handler

The CommandErrorHandler function is called with the following arguments:

• error: unknown - The error that occurred during command execution.
• args: string[] - The command arguments.
• text: string - The value of the terminal input.
• command: Command - The command being executed

The CommandErrorHandler function should return a TerminalOutputValue object. The TerminalOutputValue object can be one of the following:

• undefined - If the command does not return any output.
• string - If the command returns a string output.
• { html: JSX.Element } - If the command returns a JSX element output.

Examples

string output

const commands: Command = {
  name: 'hello',
  description: "Prints 'Hello, World!'",
  handler: () => {
    return 'Hello, World!';
  },
  waitForExecution: false,
};

JSX output

const commands: Command = {
  name: 'hello',
  description: "Prints 'Hello, World!'",
  handler: () => {
    return { html: <div>Hello, World!</div> };
  },
  waitForExecution: false,
};

Command with arguments

const commands: Command = {
  name: 'echo',
  description: 'Prints the arguments',
  usage: 'echo [args...]',
  args: ['args'],
  handler: (args) => {
    return args.join(' ');
  },
  waitForExecution: false,
};

Command with error handler

const commands: Command = {
  name: 'error',
  description: 'Throws an error',
  handler: () => {
    throw new Error('An error occurred');
  },
  onError: (error, args, command) => {
    const message = (error as Error).message;
    return `${command} thrown an error: ${message}`;
  },
  waitForExecution: false,
};

Command that waits for execution

const commands: Command = {
  name: 'wait',
  description: 'Waits for 5 seconds',
  handler: async () => {
    await new Promise((resolve) => setTimeout(resolve, 5000));
  },
};