# Svelte Bash
Svelte Bash Banner

Svelte Bash

The ultimate lightweight, fully typed, and customizable terminal component for Svelte 5.

Live Demo · 17 Examples · NPM · GitHub

NPM Version License Svelte 5 Zero Dependency CI

--- **Svelte Bash** is a terminal emulator component for Svelte 5. It has a virtual file system, a small real shell (quotes, pipes, redirects, aliases), command history, themes, an in-terminal `nano`, scripted demos, and a one-call **portfolio mode**. New here? Open the [live examples](https://svelte-bash.netlify.app/examples): each one has a working terminal and code you can copy. It uses plain scoped CSS: you do **not** need Tailwind or any other CSS framework. ## Themes

Svelte Bash in six themes: tokyo-night, dracula, gruvbox, catppuccin, nord and matrix

Pick one with a single prop: ``. Nine presets are built in, and you can pass your own colors. See [Theming](#theming). ## Key features - **Portfolio mode**: `createPortfolio({...})` gives you `about`, `projects`, `skills`, `contact`, `open`, `neofetch` and more. - **A real little shell**: `ls cat cd pwd echo mkdir touch rm cp mv alias unalias grep head tail wc find tree man history theme nano clear`, plus `|`, `>`, `>>`, `;`, `&&` and quoting. - **Virtual file system** that is never mutated (your object is copied) and can be persisted to `localStorage`. - **Window chrome**: macOS, Linux or Windows style title bars. - **9 themes** and CSS variables for everything else. - **Autoplay / bootplay / typewriter** for landing pages and docs. Autoplay really runs the commands. - **Ghost completion**, ZSH-style **syntax highlighting**, Tab completion for commands, paths and aliases. - **Accessible and mobile friendly**: `role="log"`, labelled input, on-screen Tab/arrow keys (`mobileKeys`). - **Fully typed** and covered by 260+ tests. ## Installation ```bash npm install svelte-bash ``` Requires Svelte 5. ## Portfolio in 30 seconds ```svelte ``` Visitors can type `about`, `projects`, `projects my-app`, `skills`, `contact`, `open github`, `resume`, `neofetch`, `cat projects/my-app.md`, `tree` or `theme nord`. | `createPortfolio` option | Description | |---|---| | `name` (required), `role`, `location` | Shown in the welcome message, `README.md`, `neofetch`. | | `about` | String or array of lines (`about`, `about.txt`). | | `skills` | `string[]` or `{ group: string[] }`. | | `projects` | `{ name, description, url?, tags? }[]`, also written to `projects/.md`. | | `links`, `email`, `resumeUrl` | Used by `contact`, `links`, `open`, `resume`. | | `files`, `commands`, `welcome` | Extra files, extra/override commands, custom welcome lines. | `open` and `resume` only open `http(s):` and `mailto:` URLs, in a new tab with `noopener,noreferrer`. ## Basic usage ```svelte ``` The component fills its parent: give it (or its parent) a height. ## Custom commands ```svelte ``` Give a command a description and it shows up in `help` and answers `--help`: ```svelte ``` Handlers get `(args, { stdin, cwd, user })`. Return a string, string array, number, a Svelte component, or nothing. Thrown errors are printed as errors. Custom commands take priority over built-ins and work in pipes: `echo hi | shout`. ## Persistence ```svelte ``` The whole file system is saved to `localStorage` under that key and restored on the next visit (it replaces `structure`, so deleted files stay deleted). `persist={true}` uses the key `svelte-bash-fs`. Storage errors never break the terminal. ## Controlling the terminal ```svelte ``` | Method | Description | |---|---| | `run(command)` | Execute a line as if typed. | | `clear()` | Clear the screen. | | `focus()` | Focus the input. | | `reset()` | Restore the initial file system and clear the screen. | | `getStructure()` | Copy of the current file system. | ## Autoplay and bootplay ```svelte project/hi.txt', delayAfter: 500 }, { command: 'tree' }, { command: 'deploy', output: 'Shipped! 🚀' } // fixed output instead of running ]} typingSpeed={60} /> ``` Without `output`, the command is actually executed. When the script loops, the screen and file system are reset. All timers stop when the component is destroyed. ## Shell reference | Command | Notes | |---|---| | `ls [-a] [-l] [-1] [path…]` | Hidden files with `-a`. | | `cat [-n] [file…]` | Reads stdin when piped. | | `cd`, `pwd` | `cd`, `cd ~`, `cd ..`, absolute and `~/` paths. | | `echo`, `mkdir [-p]`, `touch` | Several arguments allowed. | | `rm [-r] [-f]`, `cp [-r]`, `mv` | Several sources into a directory. Refuses unsafe moves. | | `grep [-i -v -n -c] pattern [file…]` | JavaScript regular expressions. | | `head`, `tail` (`-n N` or `-N`), `wc [-l -w -c]` | Files or stdin. | | `find [path] [-name glob] [-type f\|d]`, `tree [path]` | | | `alias`, `unalias`, `history`, `clear`, `man`, `help`, `whoami`, `date` | | | `theme [name]` | List or switch themes at runtime. | | `nano ` | `^X` saves and exits, `^C` / `Esc` cancels. | Operators: `a | b`, `a > file`, `a >> file`, `a; b`, `a && b`. Quotes (`"…"`, `'…'`) and `\ ` escapes are supported. Keyboard: `Tab` completes, `↑`/`↓` history, `Ctrl+L` clear, `Ctrl+C` cancel line (copies if text is selected). ## Customize Every option is a prop. Use ``, ``, ``, `` (or `{user}` inside a JS string) as tokens. ```svelte ``` `promptFormat` may also be a function `(ctx) => string` with `ctx = { user, host, cwd, path }`. `visualEffect` is `'none' | 'glow' | 'scanlines' | 'crt'`. `cursorStyle` is `'block' | 'bar' | 'underline'`. Animations respect `prefers-reduced-motion`. Shortcuts: `Ctrl+A` / `Ctrl+E` start / end of line, `Ctrl+U` clear line, `Ctrl+L` clear screen, `Ctrl+C` cancel (or copy a selection). More colour variables: `--sb-error`, `--sb-muted`, `--sb-cmd`, `--sb-bad`, `--sb-flag`, `--sb-str`, `--sb-op`, `--sb-font`, `--sb-font-size`, `--sb-line-height`, `--sb-padding`, `--sb-ring`, `--sb-focus`. ## Theming Presets: `dark` (default), `light`, `dracula`, `matrix`, `tokyo-night`, `nord`, `gruvbox`, `catppuccin`, `github-dark`. ```svelte ``` Or override the CSS variables from outside: ```svelte ``` ## API reference | Prop | Type | Default | Description | |------|------|---------|-------------| | `structure` | `FileStructure` | `{}` | Virtual file system (copied, never mutated). | | `commands` | `Record` | `{}` | Custom commands. | | `theme` | `string \| Theme` | `'dark'` | Preset name or colour object. | | `user` / `host` | `string` | `'user'` / `'host'` | Prompt: `user@host ~ $`. | | `promptStr` | `string` | – | Replaces the whole prompt. | | `promptFormat` | `string \| (ctx) => string` | – | Prompt template with `` `` `` ``. | | `placeholder` | `string` | – | Hint shown while the input is empty. | | `cursorStyle` / `cursorBlink` | `'block' \| 'bar' \| 'underline'` / `boolean` | `'block'` / `true` | Caret look. | | `visualEffect` | `'none' \| 'glow' \| 'scanlines' \| 'crt'` | `'none'` | Screen effect. | | `animations` | `boolean` | `true` | Turn all motion off with `false`. | | `fontFamily` / `fontSize` / `lineHeight` | `string` / `number` / `number` | – | Typography. | | `maxLines` | `number` | `1000` | Scrollback limit. | | `helpMessage` | `string \| string[] \| (names) => string` | – | Replaces the `help` output. | | `notFoundMessage` | `string` | – | Unknown-command text; `` is the typed name. | | `disabledCommands` | `string[]` | `[]` | Built-ins to switch off. | | `welcomeMessage` | `string \| string[]` | `[]` | Shown on start. | | `typewriter` | `boolean \| number` | `false` | Type the welcome message (number = ms per char). | | `windowStyle` | `'none' \| 'macos' \| 'linux' \| 'windows'` | `'none'` | Title bar style. | | `title` | `string` | `'Terminal'` | Title bar text and `aria-label`. | | `syntaxHighlight` | `boolean` | `false` | Colour commands, flags, strings, operators. | | `ghostCompletion` | `boolean` | `false` | Faint command suggestion; `Tab` accepts. | | `persist` | `boolean \| string` | – | Save the file system to `localStorage`. | | `autoplay` | `AutoplayItem[]` | – | Scripted demo (read-only terminal). | | `autoplayLoop` | `boolean` | `true` | Loop the autoplay script. | | `typingSpeed` | `number` | `50` | Autoplay typing speed (ms). | | `bootplay` / `bootSpeed` | `BootplayItem[]` / `number` | – / `10` | Fast non-interactive log. | | `readonly` | `boolean` | `false` | Show output, no input. | | `autoFocus` | `boolean` | `false` | Focus the input on mount. | | `mobileKeys` | `boolean` | `false` | Show Tab / ↑ / ↓ / Ctrl+C / Clear buttons. | | `onchange` | `(fs) => void` | – | File system changed. | | `oncommand` | `(line) => void` | – | A command line was executed. | | `class`, `style` | `string` | – | Container class / inline style. | The old `on:change={…}` event still works. ## Server-side rendering The component renders on the server (SvelteKit-safe); `localStorage` is only touched in the browser. ## Development ```bash npm install npm run dev # demo site npm test # unit + component tests npm run test:cov # with coverage npm run check # svelte-check npm run package # build ./dist ``` ## Contributing Contributions are welcome! Please run `npm run check && npm test` before opening a pull request. ## License MIT © [Yusuf Cengiz](https://github.com/YusufCeng1z) [![Star History of YusufCeng1z/svelte-bash](https://starhistory.link/YusufCeng1z/svelte-bash.svg?theme=amber&style=ascii)](https://starhistory.link/YusufCeng1z/svelte-bash)