AI Chat

Turn on the built-in AI assistant for your docs site. Covers the enable conditions and dependencies, model and endpoint routing, adding other providers, and the component and composable API, so readers can ask the docs directly within minutes.
View source

AI Chat is a chat panel built on the Vercel AI SDK. It hands the tools of the site's built-in MCP Server straight to the model, so it searches and reads the docs before answering and shows which pages it is searching or reading.

The AI Chat panel open beside a docs page

Enable

AI Chat is off by default. Three things are needed:

Install the dependencies

The AI dependencies are optional peers of the layer. Install them in your project first:

pnpm add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes

If any of them is missing once AI Chat is enabled, the build stops and prints the packages to install.

Set the environment variables

.env
# Required: its presence enables AI Chat
AI_API_KEY=your-api-key

# Optional: an OpenAI-compatible endpoint; leave empty to use AI Gateway
AI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

AI_API_KEY is read at build time: when aiChat.enabled is not set, AI Chat is enabled if the variable exists in the build environment. Your hosting platform must expose it to both the build and the runtime.

Configure the models

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  aiChat: {
    model: 'alibaba/qwen3.8-27b',
    models: [
      'alibaba/qwen3.8-27b',
      'deepseek/deepseek-v4-pro-0813'
    ]
  }
})

This is the configuration this site runs. model is the default model, models is the list readers can switch between in the panel.

AI Chat gets its documentation tools from the MCP Server, so movkNuxtDocs.mcp: false cannot be combined with AI Chat; the build fails if you try.

Explicit switch

aiChat.enabled overrides the environment check:

nuxt.config.ts
export default defineNuxtConfig({
  aiChat: {
    // true: enable even without AI_API_KEY at build time (it is still required at runtime, otherwise the endpoint answers 503)
    // false: disable even when AI_API_KEY is set
    enabled: true
  }
})

When disabled, AiChat, AiChatPanel and the other components are replaced by empty components, useAIChat() returns a disabled implementation, and the AI dependencies are left out of the bundle and of type checking. Page code never needs to check the switch.

Module options

aiChat in nuxt.config.ts:

OptionTypeDefaultDescription
enabledbooleanDerived from AI_API_KEYEnable AI Chat
modelstring''Default model id
modelsstring[][]Models available in the panel, as provider/model or model
apiPathstring'/api/ai-chat'Chat endpoint path
mcpPathstring'/mcp'MCP Server path

Model routing

On every request the server resolves the model id in this order:

  1. Registered provider: the id's prefix matches a provider registered in modelProviderRegistry, which creates the model
  2. OpenAI-compatible endpoint: AI_BASE_URL is set, so the request goes straight to that endpoint over chat completions
  3. AI Gateway: otherwise the model is called through Vercel AI Gateway

AI Gateway needs a single AI_API_KEY; models can mix providers, and ids are sent as provider/model.

With an OpenAI-compatible endpoint the prefix only picks the provider icon in the model menu and is stripped before the request: deepseek/deepseek-v4-pro-0813 is sent as deepseek-v4-pro-0813. One AI_API_KEY + AI_BASE_URL pair maps to one upstream, so models should list models that upstream serves.

ProviderAI_BASE_URL
Alibaba Cloud Model Studio (China)https://dashscope.aliyuncs.com/compatible-mode/v1
Alibaba Cloud Model Studio (International)https://dashscope-intl.aliyuncs.com/compatible-mode/v1
DeepSeekhttps://api.deepseek.com/v1
Zhipu GLMhttps://open.bigmodel.cn/api/paas/v4

Add other providers

The layer ships only @ai-sdk/openai. To use several providers at once, or one that does not speak the OpenAI protocol, install its AI SDK provider package and register it by prefix:

server/plugins/model-providers.ts
import { createAnthropic } from '@ai-sdk/anthropic'
import { modelProviderRegistry } from '#ai-chat/server/utils/modelProviders'

export default defineNitroPlugin(() => {
  const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY })

  // anthropic/claude-sonnet-5-5 lands here; the factory receives the id without its prefix
  modelProviderRegistry.register('anthropic', ({ modelId }) => anthropic(modelId))
})

Registered prefixes take precedence; every other model is still routed through AI_BASE_URL or AI Gateway.

Interface settings

The floating input, the "Explain with AI" button, shortcuts, texts, icons and suggested questions live under aiChat in app.config.ts. See the app.config reference for every field. The common ones:

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    floatingInput: true,
    explainWithAi: true,
    shortcuts: {
      focusInput: 'meta_i'
    },
    icons: {
      providers: {
        alibaba: 'i-hugeicons-qwen'
      }
    },
    faqQuestions: {
      'zh-CN': [
        { category: '安装与配置', items: ['如何从零创建文档站?', '如何启用多语言?'] }
      ],
      'en': [
        { category: 'Setup', items: ['How do I create a docs site?', 'How do I enable multiple languages?'] }
      ]
    }
  }
})
  • faqQuestions accepts a string array, a { category, items } array, or an object keyed by locale; the questions show while the panel is empty
  • texts.* fall back to the built-in translation of the current locale, so set them only to change wording
  • icons.providers maps model prefixes to icons; unmapped prefixes fall back to i-simple-icons-{provider}

Built-in entry points

Once enabled, the layer mounts these for you:

  • Header button: AiChat inside HeaderCTA toggles the panel
  • Floating input: AiChatFloatingInput at the bottom of docs pages. ⌘I / Ctrl+I focuses it, Esc blurs it, Enter sends
  • Explain with AI: a button below the table of contents that asks about the current page
  • Chat panel: AiChatPanel pushes the content aside instead of covering it; messages and the open state persist in localStorage
The floating AI input at the bottom of a docs page

Each user message carries the current page path, so the model reads that page first when asked to "explain this page".

Customization

System prompt and endpoint

The default endpoint is layer/modules/ai-chat/runtime/server/api/ai-chat.ts. Create the file matching apiPath in your project (by default server/api/ai-chat.ts) and the layer skips registering its own, letting yours change the system prompt, tools or step limit.

View the default endpoint

Tool call display

Built-in tools show messages such as "Searching docs pages". To label the MCP tools you register yourself, create a useToolCall with the same name in app/composables/:

app/composables/useToolCall.ts
export function useToolCall(state: string, toolName: string, input: Record<string, string | undefined>) {
  const done = state === 'output-available'

  return {
    toolMessage: {
      'search-api': `${done ? 'Searched' : 'Searching'} API ${input.query ?? ''}`
    } as Record<string, string>,
    toolIcon: {
      'search-api': 'i-lucide-book-open'
    } as Record<string, string>
  }
}

Return only your own tools; AiChatPanel handles the built-in ones. Unmatched tools show as "Searching {toolName}" with the i-lucide-search icon.

Built-in toolIcon
search-documentationi-lucide-book-search
get-documentation-pagei-lucide-book-open
search-composablesi-lucide-braces
search-iconsi-lucide-search
list-examplesi-lucide-codesandbox
get-examplei-lucide-codepen
get-componenti-lucide-box
get-component-metadatai-lucide-file-code

API

Components

None of these take props; they read aiChat from nuxt.config.ts and app.config.ts. With AI Chat disabled they are all replaced by AiChatDisabled, which renders an empty div.

ComponentDescription
AiChatButton that opens or closes the panel; its tooltip comes from aiChat.texts.trigger
AiChatPanelThe chat panel with messages, streaming, reasoning and tool calls
AiChatFloatingInputFloating input at the bottom of docs pages; its shortcut only responds on the docs layout
AiChatModelSelectModel menu listing aiChat.models

To use them on a custom page, mount them the way the layer does:

app/pages/playground.vue
<script setup lang="ts">
const { isEnabled } = useAIChat()
</script>

<template>
  <div>
    <AiChat />
    <template v-if="isEnabled">
      <AiChatPanel />
      <ClientOnly>
        <AiChatFloatingInput />
      </ClientOnly>
    </template>
  </div>
</template>

useAIChat()

Chat state shared across the app.

isEnabled
ComputedRef<boolean>
Whether AI Chat is enabled.
isOpen
Ref<boolean>
Whether the panel is open, persisted to localStorage.
messages
Ref<UIMessage[]>
Chat history, persisted to localStorage.
currentPage
ComputedRef<string>
Current route path, sent along with user messages.
open
(text: string) => void
Append a user message and open the panel.
toggleChat
() => void
Toggle the panel.
const { open } = useAIChat()

open('How do I enable multiple languages?')

useModels()

The model list and the current selection.

models
string[]
The value of aiChat.models.
model
Ref<string>
Current model, stored in a cookie named model and defaulting to aiChat.model.
formatModelName
(modelId: string) => string
Strip the prefix and format a display name, e.g. deepseek/deepseek-v4-pro-0813 becomes Deepseek V4 Pro 0813.
getModelIcon
(modelId: string) => string
Return the icon from aiChat.icons.providers for the id's prefix.

useHighlighter()

Returns Promise<HighlighterCore>, the Shiki instance used for code blocks in the panel, loaded on demand and created once. It bundles vue, javascript, typescript, css, html, json, yaml, markdown and bash, with the github-light and github-dark themes, matching the code blocks in the docs.

useToolCall(state, toolName, input)

The extension point for tool call display, see Tool call display. state is the AI SDK tool state ('output-available' means finished), typed as string so the layer core does not depend on the optional ai package.

Copyright © 2024 - 2026