@surfjs/vue

Name: Surf
Author: Surf

Vue 3 composables for Surf — local commands, real-time state, and Surf Live

@surfjs/vue

Vue 3 composables wrapping @surfjs/web. Register local command handlers, subscribe to Surf Live events, and sync state — all with Vue reactivity.

Installation#

bash

npm install @surfjs/vue

@surfjs/web is included as a dependency — no separate install needed.

`useSurfCommands`

vue

<script setup>
import { useSurfCommands } from '@surfjs/vue'
 
useSurfCommands({
  'theme.toggle': {
    mode: 'local',
    run: () => {
      document.documentElement.classList.toggle('dark')
      return { ok: true }
    }
  },
  'canvas.clear': {
    mode: 'local',
    run: () => {
      canvasStore.clear()
      return { ok: true }
    }
  }
})
</script>

Handlers are registered on mount and automatically cleaned up on unmount via onUnmounted.

`useSurfState`

Reactive state synced from Surf Live events:

vue

<script setup>
import { useSurfState } from '@surfjs/vue'
 
const metrics = useSurfState('metrics', { users: 0, events: 0 })
</script>
 
<template>
  <div>Online: {{ metrics.users }}</div>
</template>

Returns a Vue ref that auto-updates when the server sends surf:state or surf:patch events for the given key.

`useSurf`

Access the Surf context (requires SurfProvider):

vue

<script setup>
import { useSurf } from '@surfjs/vue'
 
const { execute, status, connected } = useSurf()
 
async function search(query) {
  const result = await execute('search', { query })
  console.log(result)
}
</script>

`useSurfEvent`

Subscribe to Surf Live events:

vue

<script setup>
import { useSurfEvent } from '@surfjs/vue'
 
useSurfEvent('notification', (data) => {
  showToast(data.message)
})
</script>

Automatically cleans up on unmount.

`SurfProvider`

Manages WebSocket connection and provides context to child components:

vue

<template>
  <SurfProvider url="wss://myapp.com/surf/ws" :endpoint="'https://myapp.com'">
    <App />
  </SurfProvider>
</template>
 
<script setup>
import { SurfProvider } from '@surfjs/vue'
</script>

| Prop | Type | Description | |------|------|-------------| | url | string | WebSocket URL for Surf Live | | endpoint | string? | Server URL for HTTP fallback | | auth | string? | Auth token | | channels | string[]? | Surf Live channels to subscribe to |

Edit this page on GitHub

Previous@surfjs/react Next @surfjs/svelte