@ably/react-web-cli v0.3.0

@ably/react-web-cli

A React component for embedding an interactive Ably CLI terminal in web applications.

Features

• Embeds a fully functional Ably CLI terminal in your React application
• Connects to a WebSocket terminal server
• Authenticates using Ably API Key and Access Token
• Handles connection state management and automatic reconnection
• Provides terminal resizing and proper terminal display
• Offers customizable UI for connection status and restart functionality

Installation

# Using npm
npm install @ably/react-web-cli

# Using yarn
yarn add @ably/react-web-cli

# Using pnpm
pnpm add @ably/react-web-cli

Prerequisites

• React 17.0.0 or higher
• A running instance of the Ably CLI terminal server (provided in the main CLI package)
• Valid Ably API Key and Access Token

Usage

import React, { useState } from 'react';
import { AblyCliTerminal } from '@ably/react-web-cli';

const MyTerminalComponent = () => {
  const [connectionStatus, setConnectionStatus] = useState('disconnected');
  
  return (
    <div style={{ height: '500px', width: '100%' }}>
      <AblyCliTerminal 
        websocketUrl="ws://localhost:8080"
        ablyApiKey="YOUR_ABLY_API_KEY"
        ablyAccessToken="YOUR_ABLY_ACCESS_TOKEN"
        onConnectionStatusChange={setConnectionStatus}
        onSessionEnd={(reason) => console.log('Session ended:', reason)}
        renderRestartButton={(onRestart) => (
          <button onClick={onRestart}>
            Restart Terminal
          </button>
        )}
      />
      <div>Terminal status: {connectionStatus}</div>
    </div>
  );
};

export default MyTerminalComponent;

Props

Setting Up a Terminal Server

The terminal server required for this component is provided in the main Ably CLI package. To run it:

1. Ensure you have the Ably CLI Docker image built:

   # In the Ably CLI repository root
   docker build --no-cache -t ably-cli-sandbox .

2. Start the terminal server:

   # In the Ably CLI repository root
   pnpm terminal-server

3. The server will start on ws://localhost:8080 by default.

Notes

• The terminal requires a container for sizing, so make sure the parent element has a defined height and width.
• The component handles reconnection automatically with exponential backoff.
• Only ably and exit commands are available in the terminal by default.
• The terminal supports full xterm.js functionality including colors and Unicode.

Example Project

For a complete example of using this component, see the web-cli example in the Ably CLI repository.

License

Apache-2.0