@npcify/vue

@npcify/vue

Vue 3.5 or later integration for Npcify characters. The NpcifyCanvas component mounts @npcify/web, resizes its canvas, and cleans up rendering and conversations when removed. Both local WebGL and protected server rendering are supported.

npm install @npcify/vue

Use this example in App.vue in your existing Vue project:

<template>
  <NpcifyCanvas :options="config" @ready="handleReady" @error="reportError"
    style="height: 480px" />
  <button :disabled="!npcify || started" @click="start">Start conversation</button>
  <div>
    <button v-for="(option, index) in replies" :key="index" @click="reply(option.label)">
      {{ option.label }}
    </button>
  </div>
  <p role="status">{{ status }}</p>
</template>

<script setup>
import { ref, shallowRef } from 'vue'
import { NpcifyCanvas } from '@npcify/vue'

const config = {
  baseUrl: 'https://api.npcify.ai',
  characterId: '<character-id>',
  apiKey: '<paste-your-scoped-api-key>',
  serverRendering: false,
}
const npcify = shallowRef(null)
const started = ref(false)
const replies = ref([])
const status = ref('')
const reportError = (error) => { status.value = error.message }
const handleReady = (client) => {
  npcify.value = client
  client.onOptionsReady(({ options }) => { replies.value = options })
}
const start = async () => {
  started.value = true
  status.value = ''
  try {
    await npcify.value.unlockAudio()
    await npcify.value.createConversation()
  } catch (error) {
    reportError(error)
    started.value = false
  }
}
const reply = async (label) => {
  replies.value = []
  try { await npcify.value.sendMessage(label) }
  catch (error) { reportError(error) }
}
</script>

Component API

• options: baseUrl, characterId, apiKey, serverRendering, and optional assetProfile (original or web-optimized-v1). See Export → Web SDK for the character's configuration. These are JavaScript props, never HTML attributes.
• @ready="handler" and @error="handler" events expose the SDK and errors.
• class/style (React: className/style) customize the outer div. It defaults to 100% width and 480px height. Give it a nonzero height.

Changing a configuration field replaces the SDK instance with a fresh canvas. Register conversation callbacks on each ready event, and clear any application state that belongs to the previous character when changing configuration. Equivalent configuration values do not restart the renderer. Pending loads are disposed when they finish after unmount; obsolete ready/error callbacks are suppressed. Mounting does not start a conversation or request audio permission. Start conversations from a user gesture, as shown above.

The component is safe to render on the server; browser loading starts after mount. Vue refs that store an SDK instance should use shallowRef so the renderer is not deeply proxied.

Create a scoped key in Export → API keys. Browser keys are visible to visitors; keep character scopes narrow and use your own backend when a key must stay private. API use is billed to the key owner. Rotation and scope changes revoke live conversation connections; downloaded assets retain their existing lifetime.

See @npcify/web for the underlying SDK, conversation methods, rendering modes, and deployment requirements. @npcify/vue also re-exports loadCharacter, createCharacter, and Character from @npcify/web when you want to import an AI character directly into a custom Three.js Scene (character.scene, character.mesh, character.audio, character.expressions, character.animation, character.update(delta)).

Maintainer release

Bump the package version, merge the validated change into develop, then run Publish npm SDKs in GitHub Actions. Homelab builds, tests and packs the SDKs; a single minimal GitHub-hosted job publishes the prepared archives through npm Trusted Publishers. Homelab verifies the registry checksums afterward. See the release guide for the workflow and trust configuration.