# client.md
# VitePress Plugin
[](https://www.npmjs.com/package/vitepress-chat)
[](https://github.com/cssnr/vitepress-chat/releases/latest)
[](https://npmx.dev/package/vitepress-chat)
[](https://bundlephobia.com/package/vitepress-chat)
[](https://github.com/cssnr/vitepress-chat/deployments/npm)
[](https://github.com/cssnr/vitepress-chat/deployments/docs)
[](https://github.com/cssnr/vitepress-chat/actions/workflows/release.yaml)
[](https://github.com/cssnr/vitepress-chat/actions/workflows/lint.yaml)
[](https://github.com/cssnr/vitepress-chat/pulse)
[](https://github.com/cssnr/vitepress-chat?tab=readme-ov-file#readme)
[](https://github.com/cssnr/vitepress-chat?tab=readme-ov-file#readme)
[](https://github.com/cssnr/vitepress-chat/graphs/contributors)
[](https://github.com/cssnr/vitepress-chat/issues)
[](https://github.com/cssnr/vitepress-chat/discussions)
[](https://github.com/cssnr/vitepress-chat/forks)
[](https://github.com/cssnr/vitepress-chat/stargazers)
A VitePress Chat Plugin providing AI Chat support trained on your docs.
Includes instructions generator plugin, or works with your existing plugin.
Securely connect to any AI provider you choose via the proxy [chat-server](server.md).
💯 100% Free to use with Zen OpenCode or Gemini Free Tier!
To get started [Install](#install) and [Setup](#setup) the plugin.
âš¡ Ask AI with the Chat button in the bottom right...
🔒 The [server](server.md) features live-streaming results, input token caching, retry on failure and much more.
Works with Claude, Gemini, OpenAI, or any [OpenAI Compatible Provider](https://ai-sdk.dev/providers/openai-compatible-providers).
[[toc]]
### Features
- Markdown Formatting with Syntax Highlighting
- Live Streams the Results in Real Time
- Works with Free Render Startup Delay
- Set Custom Button And Header Text and Link
- Includes Instructions Generation Plugin
- Set Custom File Name and Exclude Globs
- Works with Existing LLM Generation Plugins
- Small Footprint (only adds ~6KB to your theme)
- Plus all the [Server Features](server.md#features)
Built with the [AI SDK](https://ai-sdk.dev/).
💡 If you need help getting started, [support](support.md) is available.
#### Live Demos
Other sites using VitePress Chat with various configurations.
| Site | Source | Layout | Theme |
| :------------------------------------------------------ | :-------------------------------------------------------------------------------------------- | :--------: | :--------: |
| [Cache Cleaner](https://cssnr.github.io/cache-cleaner/) | [cssnr/cache-cleaner](https://github.com/cssnr/cache-cleaner) | Default | **Custom** |
| [Zipline Android](https://zipline-android.cssnr.com/) | [cssnr/zipline-android-docs](https://github.com/cssnr/zipline-android-docs) | **Custom** | Default |
| [Django Files](https://django-files.github.io/) | [django-files/django-files.github.io](https://github.com/django-files/django-files.github.io) | Default | Default |
| [Portainer Deploy](https://portainer-deploy.cssnr.com/) | [cssnr/portainer-stack-deploy-docs](https://github.com/cssnr/portainer-stack-deploy-docs) | Default | **Custom** |
## Install
From [npmjs.com](https://www.npmjs.com/package/vitepress-chat) using your favorite package manager...
```shell
npm i -D vitepress-chat
```
## Setup
There are two components, the [Chat Plugin](#chat-plugin) which adds the chat button and box.
Plus the [Instructions Generator](#instructions-generator) plugin which generates instructions.txt file.
This allows you to use this with other instructions generator plugins or existing `llms.txt` files.
### Chat Plugin
Add the plugin to your theme.
- `.vitepress/theme/index.[js,ts]`.
Using the default theme.
```typescript
import DefaultTheme from 'vitepress/theme'
import chat from 'vitepress-chat'
import 'vitepress-chat/style.css'
// https://vitepress.dev/guide/extending-default-theme
export default {
...DefaultTheme,
...chat(DefaultTheme, {
api: 'http://localhost:3000/',
}),
}
```
Using a [custom layout](https://vitepress.dev/guide/extending-default-theme#layout-slots).
```typescript
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
import chat from 'vitepress-chat'
import 'vitepress-chat/style.css'
export default {
...DefaultTheme,
...chat(MyLayout, {
api: 'http://localhost:3000/',
}),
}
```
With an Authorization header and remote server.
```typescript
export default {
...DefaultTheme,
...chat(DefaultTheme, {
api: 'https://chat-server.cssnr.com/',
headers: { Authorization: 'Basic Abc123=' },
}),
}
```
With a custom file name, to use with other generators like [vitepress-plugin-llms](https://github.com/okineadev/vitepress-plugin-llms).
```typescript
export default {
...chat(DefaultTheme, {
api: 'https://chat-server.cssnr.com/',
filePath: 'llms-full.txt',
}),
}
```
With a remote URL path.
```typescript
export default {
...chat(DefaultTheme, {
api: 'https://chat-server.cssnr.com/',
filePath: 'https://cssnr.github.io/vitepress-chat/llms.txt',
}),
}
```
You can also configure the button text, initial message and much more.
See the [ChatOptions](#chatoptions) for more details...
### Instructions Generator
Add the instruction generator plugin to your config.
- `.vitepress/config.[ts,mts]`
This generates the `instructiosn.txt` from your docs folder when you run dev or build.
```typescript
import { defineConfig } from 'vitepress'
import instructions from 'vitepress-chat/instructions'
// https://vitepress.dev/reference/site-config
export default defineConfig({
vite: {
plugins: [instructions()],
},
})
```
To exclude files/folders from the instructions use the exclude globs.
```typescript
export default defineConfig({
vite: {
plugins: [instructions({ exclude: ['index.md', 'include/**/*'] })],
},
})
```
See the [InstructionsOptions](https://github.com/cssnr/vitepress-chat/blob/master/src/instructions.ts#L8) for more details...
## Customize
### ChatOptions
All options passed to the `chat()` function. Only `api` is required.
| Option | Type | Default | Description |
| :------------------ | :----------------------- | :------------------------------------------------------------ | :---------------------------------------------------------------------- |
| `api` | `string` | **Required** | URL of the [chat server](server.md) to connect to. |
| `headers` | `Record` | — | Custom HTTP headers sent with every request to the API. |
| `buttonText` | `string` | `'AI Chat'` | Text displayed on the floating chat button. |
| `headerText` | `string \| null` | `'VitePress Chat'` | Text displayed in the chat window header. |
| `headerUrl` | `string \| null` | `'https://github.com/cssnr/vitepress-chat'` | URL the header text links to. |
| `initialMessage` | `string \| null` | — | Message automatically sent to the AI when the chat opens. |
| `aiName` | `string \| null` | `'AI'` | Label displayed above AI messages. |
| `userName` | `string \| null` | `'YOU'` | Label displayed above user messages. |
| `placeholder` | `string \| null` | `'Enter your question (use Ctrl/Shift+Enter for new lines)…'` | Placeholder text shown in the message input field. |
| `filePath` | `string` | `'instructions.txt'` | Path (or full URL) to the instructions file the server uses as context. |
| `showReasoning` | `boolean` | `false` | Show the AI's internal reasoning/thinking steps in the chat. |
| `loadingText` | `string` | `'Loading Chat…'` | Text displayed while the chat is loading. |
| `loadErrorText ` | `string` | `'Failed to load chat. Please try again.'` | Text displayed when the chat fails to load. |
| `viewReasoningText` | `string` | `'View Reasoning…'` | Text for the reasoning expand/collapse toggle. |
| `chatHeader` | `Component` | — | Vue component to replace the default header entirely. |
| `chatFooter` | `Component` | — | Vue component rendered below the message list. |
Options that optionally accept `null` will completely disable that item when passed.
The full type definition is in [`src/index.ts`](https://github.com/cssnr/vitepress-chat/blob/master/src/index.ts#L6).
### Components
You can use a custom component for the Header or Footer.
```typescript
import ChatHeader from './components/ChatHeader.vue'
import ChatFooter from './components/ChatFooter.vue'
export default {
...chat(DefaultTheme, {
api: 'https://chat-server.cssnr.com/',
chatHeader: ChatHeader,
chatFooter: ChatFooter,
}),
}
```
The custom `chatHeader` will override the current header text/link.
The custom `chatFooter` is only displayed when added.
:::details Click here to view this site's [./components/ChatFooter.vue](https://github.com/cssnr/vitepress-chat/blob/master/docs/.vitepress/theme/components/ChatFooter.vue)
<<< @/.vitepress/theme/components/ChatFooter.vue
:::
If you don't have one setup yet, configure your [Server](server.md).
---
# server.md
# Chat Server
[](https://github.com/cssnr/chat-server/releases/latest)
[](https://github.com/cssnr/chat-server/pkgs/container/chat-server)
[](https://hub.docker.com/r/cssnr/chat-server)
[](https://github.com/cssnr/chat-server/pkgs/container/chat-server)
[](https://hub.docker.com/r/cssnr/chat-server)
[](https://github.com/cssnr/chat-server/deployments/docker)
[](https://github.com/cssnr/chat-server/actions/workflows/release.yaml)
[](https://github.com/cssnr/chat-server/actions/workflows/lint.yaml)
[](https://github.com/cssnr/chat-server/pulse)
[](https://github.com/cssnr/chat-server?tab=readme-ov-file#readme)
[](https://github.com/cssnr/chat-server?tab=readme-ov-file#readme)
[](https://github.com/cssnr/chat-server/graphs/contributors)
[](https://github.com/cssnr/chat-server/issues)
[](https://github.com/cssnr/chat-server/discussions)
[](https://github.com/cssnr/chat-server/forks)
[](https://github.com/cssnr/chat-server/stargazers)
Proxy Chat Server designed to work with the VitePress Chat plugin.
Secure your API key while live-streaming responses to the client.
Works out of the box with zero configuration using Docker or Node.
💯 100% Free to use with Zen OpenCode or Gemini Free Tier!
Works with Claude, Gemini, OpenAI, or any [OpenAI Compatible Provider](https://ai-sdk.dev/providers/openai-compatible-providers).
To get started [Setup](#setup) and [Configure](#configure) the server.
âš¡ Ask AI with the Chat button in the bottom right...
[[toc]]
### Features
- Works with Claude, OpenAI, Gemini and OpenAI Compatible Providers
- Includes Chat, Completion, and Object Endpoints
- Supports Multiple Clients Simultaneously
- Live Streams the Results to the Client
- Automatic Input Token Caching
- Automatic Retry on API Failures
- Deploy with Docker or Node
- Plus all the [Client Features](client.md#features)
Built with the [AI SDK](https://ai-sdk.dev/).
## Setup
💡 The server works out-of-the-box with NO environment variables.
[](https://render.com/deploy?repo=https://github.com/cssnr/chat-server)
With Docker.
```shell
docker run -p 3000:3000 cssnr/chat-server:latest
```
With Docker Compose.
```yaml
services:
chat:
image: cssnr/chat-server:latest
environment:
MODEL: 'gemini-2.5-flash'
GOOGLE_GENERATIVE_AI_API_KEY: 'xxx'
ports:
- '3000:3000'
```
With Node.
```shell
npm i
npm start
```
_Note: you will need to export your environment variables or set them in the `settings.env` file._
For a Docker Swarm + Traefik + Basic Auth example see the [docker-compose-swarm.yaml](https://github.com/cssnr/chat-server/blob/master/docker-compose-swarm.yaml).
For a Portainer Deploy workflow see the [.github/workflows/deploy.yaml](https://github.com/cssnr/chat-server/blob/master/.github/workflows/deploy.yaml).
### Configure
💡 All variables are optional. The default `big-pickle` model works with NO API Key.
Environment Variables (can be placed in a `settings.env` file).
| Variable | Default | Description |
| :------------------------------------------ | :---------------------------------- | :------------------------------------ |
| `MODEL` | `big-pickle` | Model to Use |
| `BASE_URL` | `https://opencode.ai/zen/v1` | OpenAI Compatible Provider Base URL |
| `MAX_TOKENS` | - | Max Output Tokens |
| [PROVIDER_OPTIONS](#PROVIDER_OPTIONS) | - | Provider Options JSON String |
| [PROVIDER_USER_AGENT](#PROVIDER_USER_AGENT) | [_see below_](#PROVIDER_USER_AGENT) | OpenAI Compatible Provider User-Agent |
| [INSTRUCTIONS_CHAT](#INSTRUCTIONS) | - | System Instructions for Chat |
| [INSTRUCTIONS_COMPLETION](#INSTRUCTIONS) | - | System Instructions for Completion |
| [INSTRUCTIONS_OBJECT](#INSTRUCTIONS) | - | System Instructions for Object |
| `DISABLE_CLIENT_INSTRUCTIONS`**¹** | - | Ignore Client System Instructions |
| `AI_SDK_LOG_WARNINGS`**¹** | - | Enable SDK Warnings Logging |
| `CORS_ORIGINS` | - | Allowed CORS Origins (supports \*) |
| `PORT` | `3000` | Server Port |
| `DEBUG` | - | Set to `app` for Debug Logging |
> **¹** Boolean Variables. **True** values include: `['1', 't', 'true', 'y', 'yes', 'on']`
You must also set the API key for the `MODEL` you select.
| Variable | Description |
| :----------------------------- | :------------------------- |
| `ANTHROPIC_API_KEY` | Claude Models |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Gemini Models |
| `OPENAI_API_KEY` | OpenAI Models |
| `PROVIDER_API_KEY` | OpenAI Compatible Provider |
The `PROVIDER_API_KEY` is optional for free-tier models like `big-pickle`.
#### INSTRUCTIONS
There are mechanisms to override the instructions per-call for all clients on all endpoints.
These are used as fallback when those instructions are not sent for configurations where this is desired.
The `INSTRUCTIONS` variable (legacy) also points to the `INSTRUCTIONS_CHAT` variable (recommended).
To disable the clients ability to send custom instructions set `DISABLE_CLIENT_INSTRUCTIONS=true`
#### PROVIDER_OPTIONS
Provider Options:
For example, to disable "Reasoning" on `big-pickle` model.
```json
{ "zen": { "thinking": { "type": "disabled" } } }
```
You may need to wrap the variable in single quotes.
```text
PROVIDER_OPTIONS='{"openai":{"serviceTier":"flex","reasoningEffort":"low"}}'
```
You are responsible for providing valid options for the chosen model.
The SDK supports providing provider options for multiple providers simultaneously.
The value is only checked for valid JSON at startup and will fail at runtime if it contains invalid options.
#### PROVIDER_USER_AGENT
If BASE_URL, MODEL, and PROVIDER_API_KEY are not set (Default Zen), a custom header is set:
```text
User-Agent: opencode/version
```
This header increases the rate limit for request for the free OpenCode Zen endpoint.
To disable this without changing one of the above variables, you can set an empty value:
```text
PROVIDER_USER_AGENT=
```
Otherwise, you can set a custom User-Agent (prefix) to anything you choose:
```text
PROVIDER_USER_AGENT='my-app/1.0'
```
NOTE: The AI SDK appends a suffix to the UA: ` ai-sdk/provider-utils/x runtime/node`
## Client
### Endpoints
| Endpoint | Method | Description |
| :------------ | :----: | :------------------------------------------------------------------------------------------------------------------------------------- |
| `/chat` | `POST` | Use with [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) and [VitePress Chat](https://cssnr.github.io/vitepress-chat/) |
| `/completion` | `POST` | Use with [useCompletion](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-completion) |
| `/object` | `POST` | Use with [useObject](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-object) |
Note: The `/` endpoint (legacy) also points to the `/chat` endpoint (recommended).
#### chat
Reference:
```typescript
import { useChat } from '@ai-sdk/vue'
import { DefaultChatTransport } from 'ai'
const { messages, sendMessage, status, stop } = useChat({
transport: new DefaultChatTransport({
api: 'https://chat-server.cssnr.com/chat',
headers: { Authorization: 'Basic Abc123=' },
body: { system: 'You are a helpful assistant.' },
}),
})
```
To send System Instructions from the client, add them to the body.
#### completion
Reference:
```typescript
import { useCompletion } from '@ai-sdk/vue'
const { completion, complete, isLoading, stop } = useCompletion({
api: 'https://chat-server.cssnr.com/completion',
headers: { Authorization: 'Basic Abc123=' },
body: { system: 'You are a helpful assistant.' },
})
await complete('Explain how to set up cssnr/chat-server')
```
To send System Instructions from the client, add them to the body.
#### object
Reference:
```typescript
import { useObject } from '@ai-sdk/vue'
import { z } from 'zod'
import { zodToJsonSchema } from 'zod-to-json-schema'
const schema = z.object({ name: z.string(), age: z.number() })
const { object, submit } = useObject({
api: 'https://chat-server.cssnr.com/object',
headers: { Authorization: 'Basic Abc123=' },
schema,
})
submit({
system: 'You are a helpful assistant.',
prompt: 'Extract the name and age from: John is 30 years old.',
output: zodToJsonSchema(schema),
})
```
To send System Instructions and Output Schema from the client, add them to the body.
Note: Both `system` and `output` are custom body parameters parsed by the server.
## Development
To enable debug logs set: `DEBUG=app`
This works with no configuration using the `big-pickle` model.
You can set your environment variables in the `settings.env` file.
If using `big-pickle` for testing it is much faster to disable reasoning.
```text
PROVIDER_OPTIONS='{"zen":{"thinking":{"type":"disabled"}}}'
```
In all cases you can set the `PORT` environment variable.
With Node run.
```shell
npm run dev
```
Point your client to: http://localhost:3000/
With Docker compose _(you may need to `touch settings.env`)_.
```shell
docker compose -f docker-compose-dev.yaml up --watch --build --remove-orphans
```
Point your client to: http://localhost/
### Building
To build and test the docker image run.
```shell
bash build.sh
docker compose up
```
Source Code:
---
# support.md
# Support
[](https://github.com/cssnr/vitepress-chat/issues/new?template=1-feature.yaml)
[](https://github.com/cssnr/vitepress-chat/issues)
[](https://github.com/cssnr/vitepress-chat/discussions)
[](https://discord.gg/wXy6m2X8wY)
If you have any troubles using the application, or run into any issues, please let us know!
Every bug that can be reproduced will be fixed and Feature Request are highly desired.
Contributing is as easy as telling us [what features or changes](https://github.com/cssnr/vitepress-chat/issues/new?template=1-feature.yaml) you want to see next…
[[toc]]
### GitHub Discussions
If you have a question or need help with anything,
start a discussion in [General](https://github.com/cssnr/vitepress-chat/discussions/categories/general)
or [Q&A](https://github.com/cssnr/vitepress-chat/discussions/categories/q-a).
If you want to see a new feature, submit a [Feature Requests](https://github.com/cssnr/vitepress-chat/issues/new?template=1-feature.yaml).
[](https://github.com/cssnr/vitepress-chat/discussions)
### GitHub Issues
If you run into any problems or find a bug, please [open an issue](https://github.com/cssnr/vitepress-chat/issues).
**These reports are treated with the highest priority.**
[](https://github.com/cssnr/vitepress-chat/issues)
### Discord Chat
You can chat with us about anything [on discord](https://discord.gg/wXy6m2X8wY).
From here you can contact me directly, `Shane@111150265075298304`.
[](https://discord.gg/wXy6m2X8wY)
More information available at: [https://cssnr.com/](https://cssnr.com/)
[{ width="360" }](https://ko-fi.com/cssnr)