GitHub - YusufCeng1z/svelte-bash: A fully typed, lightweight, and customizable terminal emulator component for Svelte 5. Features a virtual file system, custom commands, themes, and autoplay mode for demos. 🚀

Svelte Bash is a high-performance terminal emulator component designed specifically for modern Svelte applications. It provides a realistic shell experience with a virtual file system, command history navigation, and advanced features like autoplay sequences for tutorials.

Note: As of v1.0.1, svelte-bash has been refactored to use Pure Vanilla CSS internally. This means it has ZERO dependencies on Tailwind CSS and will render correctly in any project (including Bootstrap, Tailwind, or plain CSS projects). You do NOT need to install Tailwind.

Whether you are building a developer portfolio, a documentation site, or a web-based CLI tool, Svelte Bash offers the perfect balance of aesthetics and functionality.

Key Features

• Lightweight & Fast: Zero external dependencies, ~4kb gzipped.
• Virtual File System: Fully functional ls -la, cd, cat, and pwd commands.
• Filesystem Mutation: Create, move, copy, and delete files/folders (mkdir, touch, rm, cp, mv).
• Persistent State (v1.2): Built-in persist prop to automatically save/load state to localStorage.
• Advanced I/O (v1.2): Redirect command outputs to files using > and >>.
• Nano Text Editor (v1.2): Built-in GNU nano clone overlay (nano <file>) to edit files directly.
• Autoplay & Bootplay (v1.2): Script commands to run automatically, or stream fast non-interactive outputs (like boot logs). (Bootplay credit: @daemy)
• ZSH Syntax Highlighting (v1.2): Live tokenization colors for commands, strings, and flags.
• Ghost Completion & Typewriter (v1.2): Premium visual interactions for a high-end CLI feel.
• Aliases: Create custom command shortcuts (e.g. alias ll='ls -la').
• Deep Theming: Includes dracula, matrix, dark, and light presets, plus full CSS control.
• Accessible: Proper focus management and keyboard history navigation (Up/Down arrows).
• TypeScript: Written in TypeScript for excellent type safety and autocomplete.

Installation

Usage

Basic Example

Import the component and pass a structure object to define the virtual file system.

<script>
  import { Terminal } from 'svelte-bash';

  const fileSystem = {
    'readme.md': '# Hello World',
    'src': {
       'app.js': 'console.log("Hi")'
    }
  };
</script>

<Terminal
    structure={fileSystem}
    user="guest"
    style="height: 300px"
/>

Filesystem Persistence (v1.2.0)

For simple apps, simply pass a string to the persist prop and the terminal will autosave the filesystem state to localStorage under that storage key:

<Terminal
    structure={initialState}
    persist="my-local-storage-key"
/>

If you need programmatic control, you can still listen to on:change:

<script>
    import { Terminal } from 'svelte-bash';

    function handleFsChange(event) {
        // event.detail contains the new FileStructure
        console.log("Filesystem changed:", event.detail);
    }
</script>

<Terminal
    structure={initialState}
    on:change={handleFsChange}
/>

Advanced I/O and Text Editor (v1.2.0)

Svelte Bash now supports basic stream redirection (> and >>) out of the box. You can write the output of any command directly to a file:

$ ls -la > output.txt
$ cat output.txt

Need to edit files? Just type nano <filename> and you'll get a fully functional, zero-dependency GNU Nano GUI embedded right in the terminal space, allowing direct modifications to strings inside the virtual filesystem!

Custom Commands & Aliases

You can extend the terminal with your own commands or presets.

<script>
  import { Terminal } from 'svelte-bash';

  const myCommands = {
    // Return a string
    hello: () => "Hello form svelte-bash!",

    // Accept arguments
    echo: (args) => args.join(' '),

    // Define an alias programmatically
    ll: () => "alias ll='ls -la'"
  };
</script>

<Terminal commands={myCommands} />

Premium Visuals & Effects (v1.2.0)

Typewriter Welcome Messages: Instead of printing immediately, welcome messages can be animated character-by-character.

<Terminal
    welcomeMessage={["Wake up, Neo..."]}
    typewriter={true} <!-- or {30} for typing speed -->
/>

ZSH-Style Syntax Highlighting & Ghost Completion: Give your terminal that beloved Oh-My-Zsh feel. syntaxHighlight parses inputs to color valid commands green, invalid ones red, strings yellow, and flags blue. ghostCompletion predicts your next move.

<Terminal
    syntaxHighlight={true}
    ghostCompletion={true}
/>

Autoplay (Show Mode)

Perfect for documentation or presentations. The terminal will automatically type and execute the provided sequence.

<Terminal
  autoplay={[
    { command: "mkdir project" },
    { command: "touch project/index.js", delayAfter: 500 },
    { command: "ls -la" }
  ]}
  typingSpeed={80}
/>

Theming

Svelte Bash allows comprehensive styling customization.

Built-in Presets:

• dark (default)
• light
• dracula
• matrix

Custom Theme Object:

<Terminal
  theme={{
    background: '#1a1b26',
    foreground: '#a9b1d6',
    prompt: '#7aa2f7',
    cursor: '#c0caf5'
  }}
/>

API Reference

Events

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Yusuf Cengiz