Skip to content

feat(assistant): can use cloudflare for assistant #1421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Barbapapazes wants to merge 2 commits into from
Closed

feat(assistant): can use cloudflare for assistant #1421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d47f2af
feat: can use cloudflare for assistatn
Barbapapazes Aug 10, 2026
8ddef0f
Apply suggestions from code review
Barbapapazes Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 51 additions & 13 deletions docs/content/en/4.ai/1.assistant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,22 +32,39 @@ By default, the assistant connects to your documentation's built-in MCP server a
::code-group

```bash [npm]
npm install ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt
npm install ai @ai-sdk/vue @ai-sdk/gateway ai-gateway-provider @ai-sdk/mcp @comark/nuxt
```

```bash [pnpm]
pnpm add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt
pnpm add ai @ai-sdk/vue @ai-sdk/gateway ai-gateway-provider @ai-sdk/mcp @comark/nuxt
```

```bash [yarn]
yarn add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt
yarn add ai @ai-sdk/vue @ai-sdk/gateway ai-gateway-provider @ai-sdk/mcp @comark/nuxt
```

::

### 2. Set up AI Gateway authentication
### 2. Choose an AI Gateway provider

Pick **one** of this method:
The assistant uses Vercel AI Gateway by default. To use Cloudflare AI Gateway, select it in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
docus: {
assistant: {
provider: 'cloudflare',
cloudflare: {
gateway: 'default'
}
}
}
})
```

### 3. Set up authentication

**Vercel AI Gateway**

**API key** — Create a key in [Vercel AI Gateway](https://vercel.com/~/ai/api-keys) and add it to your environment:

Expand All @@ -57,9 +74,21 @@ AI_GATEWAY_API_KEY=your-api-key

**OIDC (only on Vercel)** — `VERCEL_OIDC_TOKEN` is injected automatically. Nothing to add in the production. For local dev, run `vercel env pull` on a [linked project](https://vercel.com/docs/cli/link).

### 3. Deploy
**Cloudflare AI Gateway**

Set these variables at runtime:

```bash [.env]
NUXT_ASSISTANT_CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
NUXT_ASSISTANT_CLOUDFLARE_AI_GATEWAY_ID=default
NUXT_ASSISTANT_CLOUDFLARE_AIG_TOKEN=your-cloudflare-ai-gateway-token
```

Cloudflare BYOK or Unified Billing can provide upstream provider authentication, but the gateway token is still required when gateway authentication is enabled.

### 4. Deploy

Deploy your site — the assistant is available as soon as authentication is configured.
Deploy your site — the assistant is available as soon as the selected provider is configured.

## Using the Assistant

Expand Down Expand Up @@ -255,7 +284,7 @@ export default defineAppConfig({

### Disable the Assistant Entirely

The assistant is disabled when no authentication is available. To explicitly disable it, remove `AI_GATEWAY_API_KEY` from your environment:
The assistant is disabled when the selected gateway provider is not configured. To explicitly disable the Vercel assistant, remove `AI_GATEWAY_API_KEY` from your environment:

```bash [.env]
# AI_GATEWAY_API_KEY=your-api-key
Expand All @@ -271,8 +300,17 @@ Configure advanced options in `nuxt.config.ts` under `docus.assistant`.
export default defineNuxtConfig({
docus: {
assistant: {
// AI model (uses AI SDK Gateway format)
model: 'google/gemini-3-flash',
// AI Gateway provider: 'vercel' (default) or 'cloudflare'
provider: 'vercel',

// Optional build-time Cloudflare settings (runtime environment variables take precedence)
cloudflare: {
gateway: 'default'
},

// AI model (uses the selected gateway's model format)
// Defaults to google/gemini-3-flash for Vercel and
// workers-ai/@cf/zai-org/glm-4.7-flash for Cloudflare

// MCP server (path or URL)
mcpServer: '/mcp',
Expand Down Expand Up @@ -324,13 +362,13 @@ This is useful when you want the assistant to answer questions from a different

### Custom AI Model

The assistant uses `google/gemini-3-flash` by default. You can change this to any model supported by the AI SDK Gateway:
The assistant uses `google/gemini-3-flash` by default with Vercel and `workers-ai/@cf/zai-org/glm-4.7-flash` with Cloudflare. You can change this to any model supported by the selected AI Gateway:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
docus: {
assistant: {
model: 'anthropic/claude-opus-4.5'
model: 'anthropic/claude-sonnet-4-5'
}
}
})
Expand Down Expand Up @@ -375,7 +413,7 @@ function askQuestion() {

| Property | Type | Description |
| -------------------------------- | ---------------------- | --------------------------------------------------------------------------------------- |
| `isEnabled` | `ComputedRef<boolean>` | Whether the assistant is enabled (`AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` at build) |
| `isEnabled` | `ComputedRef<boolean>` | Whether the assistant is enabled for the selected gateway provider |
| `isOpen` | `Ref<boolean>` | Whether the slideover is open |
| `open(message?, clearPrevious?)` | `Function` | Open the assistant, optionally with a message |
| `close()` | `Function` | Close the assistant slideover |
Expand Down
65 changes: 52 additions & 13 deletions docs/content/fr/4.ai/1.assistant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,22 +32,39 @@ Par défaut, l'assistant se connecte au serveur MCP intégré de votre documenta
::code-group

```bash [npm]
npm install ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt
npm install ai @ai-sdk/vue @ai-sdk/gateway ai-gateway-provider @ai-sdk/mcp @comark/nuxt
```

```bash [pnpm]
pnpm add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt
pnpm add ai @ai-sdk/vue @ai-sdk/gateway ai-gateway-provider @ai-sdk/mcp @comark/nuxt
```

```bash [yarn]
yarn add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt
yarn add ai @ai-sdk/vue @ai-sdk/gateway ai-gateway-provider @ai-sdk/mcp @comark/nuxt
```

::

### 2. Configurer l'authentification AI Gateway
### 2. Choisir un fournisseur AI Gateway

Choisissez **une** de ces méthodes :
L'assistant utilise Vercel AI Gateway par défaut. Pour utiliser Cloudflare AI Gateway, sélectionnez-le dans `nuxt.config.ts` :

```ts [nuxt.config.ts]
export default defineNuxtConfig({
docus: {
assistant: {
provider: 'cloudflare',
cloudflare: {
gateway: 'default'
}
}
}
})
```

### 3. Configurer l'authentification

**Vercel AI Gateway**

**Clé API** — Créez une clé dans [Vercel AI Gateway](https://vercel.com/~/ai/api-keys) et ajoutez-la à votre environnement :

Expand All @@ -57,9 +74,21 @@ AI_GATEWAY_API_KEY=votre-cle-api

**OIDC (uniquement sur Vercel)** — `VERCEL_OIDC_TOKEN` est injecté automatiquement. Rien à ajouter en production. En local, lancez `vercel env pull` sur un [projet lié](https://vercel.com/docs/cli/link).

### 3. Déployer
**Cloudflare AI Gateway**

Définissez ces variables à l'exécution :

```bash [.env]
NUXT_ASSISTANT_CLOUDFLARE_ACCOUNT_ID=votre-identifiant-de-compte-cloudflare
NUXT_ASSISTANT_CLOUDFLARE_AI_GATEWAY_ID=default
NUXT_ASSISTANT_CLOUDFLARE_AIG_TOKEN=votre-jeton-ai-gateway-cloudflare
```

BYOK ou Unified Billing de Cloudflare peuvent fournir l'authentification du fournisseur, mais le jeton de gateway reste nécessaire lorsque l'authentification de la gateway est activée.

### 4. Déployer

Déployez votre site — l'assistant est disponible dès que l'authentification est configurée.
Déployez votre site — l'assistant est disponible dès que le fournisseur sélectionné est configuré.

## Utiliser l'Assistant

Expand Down Expand Up @@ -255,7 +284,7 @@ export default defineAppConfig({

### Désactiver l'assistant entièrement

L'assistant est désactivé quand aucune authentification n'est disponible. Pour le désactiver explicitement, supprimez `AI_GATEWAY_API_KEY` de votre environnement :
L'assistant est désactivé quand le fournisseur AI Gateway sélectionné n'est pas configuré. Pour désactiver explicitement l'assistant Vercel, supprimez `AI_GATEWAY_API_KEY` de votre environnement :

```bash [.env]
# AI_GATEWAY_API_KEY=votre-cle-api
Expand All @@ -271,8 +300,18 @@ Configurez les options avancées dans `nuxt.config.ts` sous `docus.assistant`.
export default defineNuxtConfig({
docus: {
assistant: {
// Modèle IA (utilise le format AI SDK Gateway)
model: 'google/gemini-3-flash',
// Fournisseur AI Gateway : 'vercel' (par défaut) ou 'cloudflare'
provider: 'vercel',

// Paramètres Cloudflare optionnels au build (les variables d'environnement
// d'exécution sont prioritaires)
cloudflare: {
gateway: 'default'
},

// Modèle IA (utilise le format du fournisseur sélectionné)
// Par défaut : google/gemini-3-flash avec Vercel et
// workers-ai/@cf/zai-org/glm-4.7-flash avec Cloudflare

// Serveur MCP (chemin ou URL)
mcpServer: '/mcp',
Expand Down Expand Up @@ -324,13 +363,13 @@ C'est utile lorsque vous voulez que l'assistant réponde aux questions d'une aut

### Modèle IA personnalisé

L'assistant utilise `google/gemini-3-flash` par défaut. Vous pouvez le changer pour n'importe quel modèle supporté par AI SDK Gateway :
L'assistant utilise `google/gemini-3-flash` par défaut avec Vercel et `workers-ai/@cf/zai-org/glm-4.7-flash` avec Cloudflare. Vous pouvez le changer pour n'importe quel modèle supporté par le fournisseur AI Gateway sélectionné :

```ts [nuxt.config.ts]
export default defineNuxtConfig({
docus: {
assistant: {
model: 'anthropic/claude-opus-4.5'
model: 'anthropic/claude-sonnet-4-5'
}
}
})
Expand Down Expand Up @@ -375,7 +414,7 @@ function askQuestion() {

| Propriété | Type | Description |
| -------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
| `isEnabled` | `ComputedRef<boolean>` | Si l'assistant est activé (`AI_GATEWAY_API_KEY` ou `VERCEL_OIDC_TOKEN` au build) |
| `isEnabled` | `ComputedRef<boolean>` | Si l'assistant est activé pour le fournisseur AI Gateway sélectionné |
| `isOpen` | `Ref<boolean>` | Si le panneau est ouvert |
| `open(message?, clearPrevious?)` | `Function` | Ouvrir l'assistant, optionnellement avec un message |
| `close()` | `Function` | Fermer le panneau de l'assistant |
Expand Down
37 changes: 32 additions & 5 deletions layer/modules/assistant/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ A Nuxt module that provides an AI-powered chat interface using MCP (Model Contex
2. Install the required dependencies:

```bash
pnpm add @ai-sdk/mcp @ai-sdk/vue @ai-sdk/gateway ai motion-v shiki shiki-stream
pnpm add @ai-sdk/mcp @ai-sdk/vue @ai-sdk/gateway ai ai-gateway-provider motion-v shiki shiki-stream
```

3. Add the module to your `nuxt.config.ts`:
Expand All @@ -37,7 +37,9 @@ export default defineNuxtConfig({
})
```

4. Authenticate to AI Gateway in one of two ways:
4. Choose an AI Gateway provider and authenticate it:

**Vercel AI Gateway (default)**

- **`AI_GATEWAY_API_KEY`** — Set it in the Vercel project env UI (and locally in `.env` if you want).
- **OIDC** — On Vercel, `VERCEL_OIDC_TOKEN` is injected automatically; you do **not** add it (or an API key) in the dashboard. For local builds, run `vercel env pull` on a linked project so `.env` contains the token:
Expand All @@ -50,7 +52,30 @@ AI_GATEWAY_API_KEY=your-gateway-key
VERCEL_OIDC_TOKEN=...
```

> **Note:** The module enables when `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` is present at build time. On Vercel, OIDC covers that without you creating env vars in the UI. If neither is available at build, the module stays disabled and a warning is logged.
**Cloudflare AI Gateway**

Configure the provider in `nuxt.config.ts`:

```ts
docus: {
assistant: {
provider: 'cloudflare',
cloudflare: {
gateway: 'default',
},
},
}
```

Set these variables at runtime:

- **`NUXT_ASSISTANT_CLOUDFLARE_ACCOUNT_ID`** — Cloudflare account ID.
- **`NUXT_ASSISTANT_CLOUDFLARE_AI_GATEWAY_ID`** — Cloudflare AI Gateway ID.
- **`NUXT_ASSISTANT_CLOUDFLARE_AIG_TOKEN`** — Cloudflare AI Gateway token.

Cloudflare BYOK or Unified Billing can provide upstream provider authentication, but the gateway token is still required when gateway authentication is enabled.

> **Note:** The module enables when the selected provider has its required configuration at build time. If it is not configured, the assistant stays disabled and a warning is logged.

## Usage

Expand Down Expand Up @@ -158,7 +183,9 @@ clearMessages()
|--------|------|---------|-------------|
| `apiPath` | `string` | `/__docus__/assistant` | API endpoint path for the chat |
| `mcpServer` | `string` | `/mcp` | MCP server path or full URL (e.g., `https://docs.example.com/mcp` for external servers) |
| `model` | `string` | `google/gemini-3-flash` | AI model identifier for AI SDK Gateway |
| `provider` | `'vercel' \| 'cloudflare'` | `vercel` | AI Gateway provider to use |
| `cloudflare` | `object` | `{}` | Cloudflare account and gateway settings; used when `provider` is `cloudflare` |
| `model` | `string` | `google/gemini-3-flash` (Vercel) / `workers-ai/@cf/zai-org/glm-4.7-flash` (Cloudflare) | AI model identifier for the selected gateway |

## Components

Expand Down Expand Up @@ -208,7 +235,7 @@ Composable for syntax highlighting code blocks with Shiki.
- Nuxt 4.x
- Nuxt UI 3.x (for `USlideover`, `UButton`, `UTextarea`, `UChatMessages`, etc.)
- An MCP server running (path configurable via `mcpServer`)
- `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` at build time
- Credentials for the selected AI Gateway provider at build time

## Customization

Expand Down
Loading
Loading