---
title: "Nuxt"
description: "Run an eve agent and a Nuxt app as one project with the eve/nuxt module."
---

The `eve/nuxt` module runs a Nuxt frontend and an eve agent as a single project from one dev server and one Vercel deploy. The auto-imported [`useEveAgent`](./use-eve-agent-vue) composable finds the mounted routes on its own, so there's no CORS to configure and no URL env vars to keep in sync.

## 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 naming a host:

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

const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
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](./overview#authenticate-browser-requests) for the default fail-closed behavior and 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 through it. As far as the browser knows, everything is 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 Build Output [`services`](https://vercel.com/docs/services) for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Nuxt app itself remains the default app. No `vercel.json` is required. By default the generated service runs the installed eve binary from the agent root, so the agent directory does not 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 does not 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, build and serve eve from a separate directory (set `eveRoot` to it) so the two outputs do not overwrite each other. 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 owns routing. It must include the eve service (`framework: "eve"`) and a rewrite that exposes the eve transport, 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" } }]
}
```

### Migrating from experimentalServices

Earlier versions of the module wrote the legacy `experimentalServices` field into `vercel.json`. Vercel no longer routes that model — deployments build both services but every `/eve/v1/*` request returns a platform NOT_FOUND — so the module now ignores the field and warns when it sees one. Migrate either way:

- **Generated (default).** Delete `vercel.json` (or just its `experimentalServices` block) and set the project's Framework Preset back to Nuxt.js. The module generates the eve service and its routing on every Vercel build.
- **Hand-maintained.** Replace `experimentalServices` with the stable `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](../deployment/overview)