@fluxlay/react

SDK for building Fluxlay wallpapers with React.

Installation

npm install @fluxlay/react
# or
pnpm add @fluxlay/react

Also import the stylesheet in your entry file:

import "@fluxlay/react/dist/sdk.css";

API

useBackendMouse()

Subscribes to the global mouse position streamed from the Fluxlay backend. The Y axis is inverted so that positive values point upward (standard mathematical coordinates).

import { useBackendMouse } from "@fluxlay/react";

function Wallpaper() {
  const { x, y } = useBackendMouse();
  return <div style={{ transform: `translate(${x}px, ${y}px)` }} />;
}

useShell(commandId, options?)

Executes a shell command declared in fluxlay.yaml and optionally renders its output into a terminal.

import { useShell } from "@fluxlay/react";

function Wallpaper() {
  const { result, isRunning } = useShell("my-command", {
    refreshInterval: 5000, // re-run every 5 seconds
  });
  return <pre>{result?.stdout}</pre>;
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | refreshInterval | number | 30000 | Auto-refresh interval in ms. 0 to disable. | | showStdout | boolean | true | Write stdout to the linked terminal. | | showStderr | boolean | false | Write stderr to the linked terminal. | | terminal | TerminalInstance | — | Terminal instance from useTerminal. | | columns | number | — | Pseudo-terminal column width. | | lines | number | — | Pseudo-terminal row height. |

Returns { execute, isRunning, error, result }.

useTerminal(options?)

Creates a read-only xterm terminal. Attach terminalRef to a <div> container.

import { useTerminal, useShell, TerminalThemes } from "@fluxlay/react";

function Wallpaper() {
  const { terminalRef, instance } = useTerminal({
    fontSize: 13,
    theme: TerminalThemes.tokyoNight,
  });
  useShell("my-command", { terminal: instance });
  return <div ref={terminalRef} />;
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | fontSize | number | 12 | Font size in pixels. | | fontFamily | string | system monospace | CSS font-family string. | | theme | ITheme | TerminalThemes.dark.default | xterm color theme. |

Returns { terminalRef, instance }.

runShell(commandId, options?)

Low-level function to run a shell command imperatively.

import { runShell } from "@fluxlay/react";

const result = await runShell("my-command", { columns: 80, lines: 24 });
console.log(result.stdout);

TerminalThemes

Pre-built xterm color themes to pass to useTerminal.

| Key | Variants | |-----|----------| | dark | default, modern | | light | default, modern | | nord | — | | dracula | — | | gruvbox | dark, light | | solarized | dark, light | | oneDark | — | | catppuccin | latte, frappe, macchiato, mocha | | monokaiPro | — | | tokyoNight | — | | nightOwl | — | | everforest | dark, light |