@webgui/client

One library for the WebGUI Minecraft mod. A framework-agnostic core, plus React, Vue and Svelte bindings that are thin wrappers over it.

Replaces @webgui/react, @webgui/vue and @webgui/svelte, which were three parallel implementations of the same logic and had to be updated in lockstep every time the mod gained an event. Those packages still work and now re-export this one.

npm install @webgui/client

React, Vue and Svelte are optional peer dependencies — importing the core pulls in none of them.

Plain JavaScript

import { clientStore, deathStore, runCommand, respawn, isInMod } from '@webgui/client';

if (isInMod()) {
  clientStore.subscribe(() => {
    const c = clientStore.get();
    document.querySelector('#hp').textContent = `${c.health} / ${c.maxHealth}`;
  });
}

Every store has the same three members:

| Member | Purpose | |---|---| | subscribe(listener) | Registers a no-argument listener; returns the unsubscribe function. | | get() | The current value, or null before the mod has sent anything. | | getServerSnapshot() | Always null — there is no mod during server rendering. |

React

import { useWebGUIClient, useWebGUIDeath, useRespawn } from '@webgui/client/react';

function DeathScreen() {
  const death = useWebGUIDeath();
  const respawn = useRespawn();
  if (!death) return null;

  return (
    <div>
      <h1>You died</h1>
      <p>{death.deathMessage}</p>
      {death.canRespawn && <button onClick={respawn}>Respawn</button>}
    </div>
  );
}

Vue

<script setup lang="ts">
import { useWebGUIDeath, respawn } from '@webgui/client/vue';
const death = useWebGUIDeath();
</script>

<template>
  <div v-if="death">
    <h1>You died</h1>
    <p>{{ death.deathMessage }}</p>
    <button v-if="death.canRespawn" @click="respawn">Respawn</button>
  </div>
</template>

Svelte

<script lang="ts">
  import { webguiDeath, respawn } from '@webgui/client/svelte';
</script>

{#if $webguiDeath}
  <h1>You died</h1>
  <p>{$webguiDeath.deathMessage}</p>
  {#if $webguiDeath.canRespawn}
    <button on:click={respawn}>Respawn</button>
  {/if}
{/if}

API

State

| Core | React | Vue | Svelte | |---|---|---|---| | clientStore | useWebGUIClient() | useWebGUIClient() | webguiClient | | entityStore | useWebGUIEntity() | useWebGUIEntity() | webguiEntity | | deathStore | useWebGUIDeath() | useWebGUIDeath() | webguiDeath | | selectorStore(fn) | useWebGUISelector(fn) | useWebGUISelector(fn) | webguiSelector(fn) |

Use a selector when a component needs one field. The mod pushes client updates several times a second, so a component reading only health should not re-render every time the player walks.

Actions

postToGame, closeGui, runCommand, respawn — plain functions in every entry point. React also exports usePostToGame, useCloseGui, useRunCommand and useRespawn, which return the same functions with stable identity for dependency arrays.

All four are no-ops outside the mod, so a page can run in a normal browser tab without guards at every call site.

Helpers

| Core | React | Vue | Svelte | |---|---|---|---| | isInMod() | — | — | — | | isReady(value) | — | — | — | | getToken(param?) | useWebGUIToken(param?) | useWebGUIToken(param?) | webguiToken(param?) | | onWebGUIEvent(name, fn) | useWebGUIEvent(name, fn) | useWebGUIEvent(name, fn) | onWebGUIEvent(name, fn) |

Events that fire before your code runs

The mod sends webgui:death once, immediately after the document loads, and sets window.webgui.client / .entity / .death before that. Every store reads those snapshots at import time, so a component that mounts a tick late still sees the value — a bare addEventListener in a component would miss it.

Migrating

The hook and store names are unchanged, so the import path is usually the only edit:

- import { useWebGUIClient } from '@webgui/react'
+ import { useWebGUIClient } from '@webgui/client/react'

- import { webguiClient } from '@webgui/svelte'
+ import { webguiClient } from '@webgui/client/svelte'

One rename: Svelte's onWebGUIEvent and webguiToken now also exist under those names in the core, and the React/Vue entries expose them as useWebGUIEvent / useWebGUIToken as before.

License

MIT