Getting Started

Install ai-elements-nuxt and ship a streaming chat in minutes.

1. Install

Core (always required)

pnpm add ai-elements-nuxt ai @ai-sdk/vue

Available on npm as ai-elements-nuxt.

Choose a model provider (at least one required for production)

pnpm add @ai-sdk/openai        # OpenAI / GPT-4o
# pnpm add @ai-sdk/anthropic   # Anthropic / Claude
# pnpm add @ai-sdk/google      # Google / Gemini
# pnpm add @ai-sdk/mistral     # Mistral

Full provider list → ai-sdk.dev/providers

Agents only

pnpm add zod   # for tool parameter schemas

Set your API key

# .env
OPENAI_API_KEY=sk-...

Nuxt reads .env automatically — process.env.OPENAI_API_KEY is available in server routes. See the AI SDK provider docs for each provider's env variable name.

Install from GitHub (optional)

Use the latest commit from the repository instead of the npm release:

pnpm add github:albegosu/ai-elements-nuxt

With strict pnpm build settings, allow lifecycle scripts in pnpm-workspace.yaml: allowBuilds: { ai-elements-nuxt: true }

2. Register the module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['ai-elements-nuxt'],
  aiElements: { defaultStyles: true },
})

3. Add a chat API route

Create server/api/chat.post.ts:

// Start with mock (no API key needed):
import { createMockChatHandler } from 'ai-elements-nuxt/server'
export default createMockChatHandler()

// Swap for production:
// import { createChatHandler } from 'ai-elements-nuxt/server'
// import { openai } from '@ai-sdk/openai'
// export default createChatHandler({ model: openai('gpt-4o') })

Need an agent with tools? Building an Agent covers createAgentHandler + zod schemas.

4. Build the page

<script setup lang="ts">
const { aiMessages, input, handleSubmit, isStreaming } = useAiChat({ api: '/api/chat' })
</script>

<template>
  <AiMessage v-for="(msg, i) in aiMessages" :key="i" v-bind="msg" />
  <form @submit="handleSubmit">
    <AiPromptInput v-model="input" :loading="isStreaming" />
  </form>
</template>

Try the live demo on Streaming playground.

What do you need?

Goal	Key components	Composable	Server handler
Streaming chat	`AiMessage`, `AiPromptInput`	`useAiChat`	`createChatHandler`
Agent with tools	+ `AiAgent`, `AiTool`, `AiToolApproval`	`useAiAgent`, `useAiTools`	`createAgentHandler`
Persisted chat	same as chat	`useAiChatPersisted`	same as chat