@yak-io/nuxt

Nuxt 3 integration for the Yak embeddable chat widget. Provides a plugin-compatible factory that auto-mounts on app:mounted and provides the widget API via Nuxt's plugin system.

Installation

pnpm add @yak-io/nuxt

Quickstart

1. Create a Nuxt plugin

// plugins/yak.client.ts
import { defineNuxtPlugin } from "#app";
import { createYakProvider, enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/nuxt";

export default defineNuxtPlugin((nuxtApp) => {
  const runtimeConfig = useRuntimeConfig();

  const yak = createYakProvider({
    appId: runtimeConfig.public.yakAppId,
    theme: { position: "bottom-right", colorMode: "system" },
    trigger: { label: "Ask with AI" },
    getConfig: async () => {
      const res = await fetch("/api/yak");
      return res.json();
    },
    onToolCall: async (name, args) => {
      const res = await fetch("/api/yak", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name, args }),
      });
      const data = await res.json();
      if (!data.ok) throw new Error(data.error);
      return data.result;
    },
    onRedirect: (path) => {
      navigateTo(path);
    },
  });

  // Mount on client, clean up on HMR
  nuxtApp.hook("app:mounted", () => yak.mount());
  if (import.meta.hot) {
    import.meta.hot.dispose(() => yak.destroy());
  }

  return {
    provide: {
      yak,
      yakLogging: { enableYakLogging, disableYakLogging, isYakLoggingEnabled },
    },
  };
});

2. Access in components

// Any component <script setup>
const { $yak } = useNuxtApp();
const { open, openWithPrompt, isOpen, isReady } = $yak;

isOpen and isReady are Vue readonly refs:

<template>
  <button @click="open">Open Chat</button>
  <span v-if="isOpen">Chat is open</span>
</template>

3. Subscribe to tool events

const { $yak } = useNuxtApp();

$yak.subscribeToToolEvents((event) => {
  if (event.ok && event.name.startsWith("tasks.")) {
    refreshTasks();
  }
});

API Reference

createYakProvider(options)

Creates a Yak widget instance. Returns a YakApi with Vue-reactive refs for reactive state.

You must call yak.mount() on the client side (e.g., in the app:mounted hook) and yak.destroy() when cleaning up.

Options:

| Option | Type | Description | |--------|------|-------------| | appId | string | Your Yak app ID | | getConfig | ChatConfigProvider | Async function returning routes + tools. Called on first open. | | onToolCall | ToolCallHandler | Handle tool invocations from the assistant | | onGraphQLSchemaCall | GraphQLSchemaHandler | Handle GraphQL schema tool calls | | onRESTSchemaCall | RESTSchemaHandler | Handle REST/OpenAPI schema tool calls | | theme | Theme | Position, color mode, and custom colors | | onRedirect | (path: string) => void | Navigation handler (defaults to window.location.assign) | | disableRestartButton | boolean | Hide the restart session button | | trigger | boolean \| TriggerButtonConfig | Built-in trigger button |

YakApi

type YakApi = {
  isOpen: DeepReadonly<Ref<boolean>>;  // Vue readonly ref
  isReady: DeepReadonly<Ref<boolean>>; // Vue readonly ref
  open: () => void;
  close: () => void;
  openWithPrompt: (prompt: string) => void;
  subscribeToToolEvents: (handler: ToolCallEventHandler) => () => void;
  mount: () => void;    // Call in app:mounted hook
  destroy: () => void;  // Call on HMR dispose / cleanup
};

Logging

import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/nuxt";

enableYakLogging();    // Enable verbose SDK logs
disableYakLogging();   // Disable SDK logs
isYakLoggingEnabled(); // → boolean

Types

import type {
  YakProviderOptions,
  YakApi,
  ToolCallEventHandler,
  ChatConfigProvider,
  ToolCallHandler,
  ToolCallEvent,
  Theme,
  TriggerButtonConfig,
  WidgetPosition,
} from "@yak-io/nuxt";

License

Proprietary — see LICENSE file.