Svelte Library

@webgui/svelte provides Svelte stores and TypeScript types for SPAs running inside the WebGUI mod. It exposes the injected window.webgui API as stores you consume with the $ syntax — no boilerplate.

Same data, different framework

@webgui/svelte, @webgui/react and @webgui/vue expose the same data and actions — pick the one for your framework. The full WebGUIClient / WebGUIEntity shapes are documented on the React Library page.

Installation

npm install @webgui/svelte

Requires Svelte 4+ as a peer dependency. The package version tracks the mod version (e.g. @webgui/svelte@1.6.0 targets WebGUI 1.6.0).

Quick start

<script lang="ts">
  import { webguiClient, isInMod } from '@webgui/svelte'
</script>

{#if !isInMod()}
  <p>Open this page inside Minecraft.</p>
{:else if $webguiClient}
  <p>Hello, {$webguiClient.username}</p>
{:else}
  <p>Waiting for mod data…</p>
{/if}

Stores

webguiClient

const webguiClient: Readable<WebGUIClient | null>

The latest client snapshot (pushed at 20 TPS). null before the first push or outside the mod.

<span>{$webguiClient?.username}</span>

webguiEntity

const webguiEntity: Readable<WebGUIEntity | null>

The entity the player right-clicked to open this GUI (via /webgui bind entity), or null if opened via command.

webguiSelector

function webguiSelector<T>(
  selector: (client: WebGUIClient) => T,
  equalFn?: (a: T, b: T) => boolean,
): Readable<T | null>

Derives a store from the client snapshot. Its value only changes when the selected value changes (per equalFn, default Object.is), so subscribers don't fire on every tick.

<script lang="ts">
  import { webguiSelector } from '@webgui/svelte'
  const username = webguiSelector((c) => c.username)
</script>

<span>{$username}</span>

Actions

postToGame

function postToGame(payload: PostToGamePayload): void

Sends a message to the game via the mod's CEF router.

postToGame({ channel: 'log', level: 'info', message: 'shop opened' })
postToGame({ channel: 'shop:buy', itemId: 'minecraft:diamond', qty: 1 })

closeGui

function closeGui(): void

Closes the active GUI screen or HUD overlay.

runCommand

function runCommand(command: string): void

Runs a command as the player, exactly as if they typed it in chat. Only works when the page is on a trustedCommandOrigins origin; otherwise the mod drops it.

<button on:click={() => runCommand('spawn')}>Teleport to spawn</button>

webguiToken

function webguiToken(paramName?: string): string | null

The signed token the mod appended to the page URL, or null when absent. Static for the page lifetime. See Backend Token Verification.

onWebGUIEvent

function onWebGUIEvent<T = unknown>(
  eventName: string,
  handler: (data: T) => void,
): () => void

Subscribes to a named event pushed from the server via WebviewApi.emitToPage. Returns an unsubscribe function — return it from onMount, or call it in onDestroy. See Events.

<script lang="ts">
  import { onMount } from 'svelte'
  import { onWebGUIEvent } from '@webgui/svelte'

  let balance = 0
  onMount(() =>
    onWebGUIEvent<{ balance: number }>('walletUpdate', (d) => { balance = d.balance }),
  )
</script>

Utils

isInMod() — true when window.webgui is present. isReady(client) — true once a snapshot has arrived.

TypeScript

All types are exported from the package root (WebGUIClient, WebGUIEntity, PostToGamePayload, …). The package augments window.webgui and the webgui:client / webgui:entity events globally — add "types": ["@webgui/svelte"] to your tsconfig.json to use window.webgui directly.