---
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, mounted at `/eve/v1/*`. An `agents/` workspace mounts each member at `/eve/<name>/v1/*` instead. 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 an eve dev server for each agent beside `nuxt dev` and proxies the eve routes to it. The browser talks only to the Nuxt origin. 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) per agent and routes its transport requests to it before filesystem routing. The Nuxt app serves everything else, and no `vercel.json` is required. When `vercel.json` declares services, or a `vercel.ts` composes them with `withEve` from `eve/vercel`, the module generates nothing and that configuration controls routing. By default, each generated service runs the installed eve binary from its agent root, so agent directories don't need their own `package.json`. When the agents need their 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 proxy rules that send the eve routes to `EVE_NUXT_PRODUCTION_ORIGIN`, or to `http://127.0.0.1:4274` when that variable is unset. With `EVE_NUXT_PRODUCTION_ORIGIN`, each `agents/` workspace member keeps its own path on that host (`/eve/<name>/v1`). Without it, each member runs as its own server serving `/eve/v1`, on consecutive ports from `4274` in alphabetical order of member name (`4274`, `4275`, ...). Override the first 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)