---
title: Nuxt
description: Run an eve agent and a Nuxt app as one project with the eve/nuxt module.
url: "https://eve.dev/docs/guides/frontend/nuxt"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The `eve/nuxt` module runs a Nuxt frontend and an eve agent as one project, with one dev server and one Vercel deploy. The auto-imported [`useEveAgent`](./use-eve-agent-vue) composable finds the mounted routes on its own, so you configure no CORS or URL env vars.

## Prerequisites

- The `eve` package installed in your project (`npm install eve@latest`).
- An existing eve agent directory. If you don't have one, start from [Getting started](../../getting-started).
- A Nuxt app to mount the agent in.

## Register the module

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
  modules: ["eve/nuxt"],
});
```

The module looks for an `agent/` folder in the Nuxt project root. Pass `eveRoot` when the agent lives elsewhere:

```ts
export default defineNuxtConfig({
  modules: ["eve/nuxt"],
  eve: {
    eveRoot: "../my-agent",
  },
});
```

### `eve/nuxt` options

All fields are optional.

| Option               | Type     | Default           | Purpose                                                                                                           |
| -------------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `eveRoot`            | `string` | Nuxt project root | eve project root, relative to the Nuxt project root unless absolute.                                              |
| `eveBuildCommand`    | `string` | generated         | Build command for the generated eve Vercel service.                                                               |
| `devServerTimeoutMs` | `number` | `180000`          | Maximum time to wait for the eve development server to start, including when another Nuxt process is starting it. |

For slow cold starts, increase the development timeout:

```ts
export default defineNuxtConfig({
  modules: ["eve/nuxt"],
  eve: {
    devServerTimeoutMs: 300_000,
  },
});
```

## Call the composable

`useEveAgent` (`eve/vue`) is auto-imported, so a component calls it without an explicit import and without passing `baseUrl`:

```vue
<script setup lang="ts">
const { status, send } = useEveAgent();

const isBusy = computed(() => status.value === "busy");
const isInputDisabled = computed(() => isBusy.value || status.value === "resuming");

const message = ref("");

async function handleSubmit() {
  const text = message.value.trim();
  if (!text || isInputDisabled.value) return;
  message.value = "";
  await send(text);
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="message" :disabled="isInputDisabled" />
    <button type="submit" :disabled="isInputDisabled">Send</button>
  </form>
</template>
```

The browser still needs a production authentication policy. See [Authenticate browser requests](/docs/guides/frontend#authenticate-browser-requests) for the default policy, which rejects unverified requests, and for channel configuration.

## Dev vs deploy topology

- **Local dev.** `npm run dev` starts the eve dev server next to `nuxt dev` and proxies the eve routes to it. The browser talks only to the Nuxt origin. Concurrent Nuxt processes for the same eve root share one eve dev server. Set `EVE_BASE_URL` to proxy to an eve dev server you already run instead.

- **Vercel.** The web app and the eve runtime deploy as a single project. On Vercel builds, the module adds an eve [service](https://vercel.com/docs/services) and routes `/eve/v1/**` to it before filesystem routing. The Nuxt app serves everything else, and no `vercel.json` is required. By default, the generated service runs the installed eve binary from the agent root, so the agent directory doesn't need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:

  ```ts
  export default defineNuxtConfig({
    modules: ["eve/nuxt"],
    eve: {
      eveBuildCommand: "npm run build:eve",
    },
  });
  ```

- **Non-Vercel hosts.** The module doesn't start eve in production; run the eve service yourself. `nuxt build` writes a proxy rule that sends `/eve/v1/**` to `EVE_NUXT_PRODUCTION_ORIGIN`, or to `http://127.0.0.1:4274` when that variable is unset. Override the local port with `EVE_NUXT_PRODUCTION_PORT`. Set these variables when you run `nuxt build`, because the destination is fixed in the build output:

  ```bash
  EVE_NUXT_PRODUCTION_ORIGIN=https://agent.example.com npm run build
  ```

  `eve build` and `nuxt build` both write `.output/`. When the agent lives in the Nuxt project root, the two outputs overwrite each other. Build and serve eve from a separate directory instead, and set `eveRoot` to it. See [Self-host eve](../deployment/self-hosting) for running the eve service.

## Managing vercel.json yourself

When `vercel.json` declares [`services`](https://vercel.com/docs/services), the module generates nothing, and your configuration controls routing. It must include the eve service (`framework: "eve"`) and a rewrite that sends `/eve/v1/*` requests to it, or the module fails the build:

```json title="vercel.json"
{
  "services": {
    "web": { "root": ".", "framework": "nuxtjs" },
    "eve": { "root": "agent", "framework": "eve", "buildCommand": "eve build" }
  },
  "rewrites": [{ "source": "/eve/v1/(.*)", "destination": { "service": "eve" } }]
}
```

### Remove `experimentalServices`

Vercel doesn't route the `experimentalServices` field in `vercel.json`: both services build, but every `/eve/v1/*` request returns `NOT_FOUND`. The module ignores the field and warns that `vercel.json defines experimentalServices`. Remove it in one of two ways:

- **Generated (default).** Delete `vercel.json` (or its `experimentalServices` block) and set the project's Framework Preset to Nuxt.js. The module generates the eve service and its routing on every Vercel build.
- **Hand-maintained.** Replace `experimentalServices` with the `services` and `rewrites` shown above, and keep the "Services" Framework Preset.

## What to read next

- [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API
- [Auth & route protection](../auth-and-route-protection)
- [Deployment](/docs/guides/deployment)

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)