---
title: "Configuration"
description: "Every convex module option, the runtime config keys, the #convex/* import aliases, and the Convex-aware Content Security Policy defaults."
canonical_url: "https://nuxt-convex-module.dev/getting-started/configuration"
---
# Configuration

> Every convex module option, the runtime config keys, the #convex/* import aliases, and the Convex-aware Content Security Policy defaults.

## Module options (`convex`)

Everything under the `convex` key of `nuxt.config.ts`. "Auto-detect" means the package is named in your app's own `package.json` and resolves; a package that only resolves — hoisted from a sibling app in a monorepo — switches nothing on, so set the option to `true` to use one a layer or the workspace root provides.

<field-group>
<field name="url" type="string" default="NUXT_PUBLIC_CONVEX_URL, then CONVEX_URL">

Convex deployment URL. In development, `.env.local` counts as environment too, under the real one.

</field>

<field name="siteUrl" type="string" default="NUXT_PUBLIC_CONVEX_SITE_URL, then CONVEX_SITE_URL">

Convex `.site` URL — HTTP actions and the Better Auth endpoints. Read from `.env.local` in development, like `url`.

</field>

<field name="betterAuth" type="boolean | BetterAuthModuleOptions" default="auto-detect: @convex-dev/better-auth">

Force the [Better Auth](https://nuxt-convex-module.dev/components/better-auth) integration on or off, or configure it with the three keys below.

</field>

<field name="betterAuth.authClient" type="string" default="the bundled client">

Path to your own auth-client module, absolute or relative to the project root — see [bring your own auth client](https://nuxt-convex-module.dev/components/better-auth#bring-your-own-auth-client).

</field>

<field name="betterAuth.crossDomainCallbackRoute" type="string" default="'' (unrestricted)">

The one route allowed to exchange a cross-domain `?ott=` token — see [cross-domain one-time tokens](https://nuxt-convex-module.dev/getting-started/security#cross-domain-one-time-tokens).

</field>

<field name="betterAuth.loginPath" type="string" default="/login">

Where the `convex-auth` route middleware sends unauthenticated visitors.

</field>

<field name="clerk" type="boolean" default="auto-detect: @clerk/vue">

Force the [Clerk](https://nuxt-convex-module.dev/components/clerk) adapter on or off.

</field>

<field name="auth0" type="boolean" default="auto-detect: @auth0/auth0-vue">

Force the [Auth0](https://nuxt-convex-module.dev/components/auth0) adapter on or off.

</field>

<field name="polar" type="boolean" default="auto-detect: @convex-dev/polar">

Force the [Polar](https://nuxt-convex-module.dev/components/polar) components on or off.

</field>

<field name="security" type="boolean" default="auto-detect (dependency or in modules)">

Force the [nuxt-security](https://nuxt-convex-module.dev/getting-started/security) integration on or off.

</field>

<field name="autoImports" type="boolean | 'prefixed'" default="true">

Which names are auto-imported. `true` registers every composable, component and Nitro helper under its upstream name (`useQuery`, `<Authenticated>`, `fetchQuery`) and, where one exists, its prefixed twin (`useConvexQuery`). `'prefixed'` registers only the names carrying `Convex` — `useConvexQuery`, `useConvexMutation`, `<ConvexImage>`, `provideConvexAuth`, `convexAuth`, … — so a bare name never collides with another module's (`@pinia/colada-nuxt` and `@nuxtjs/apollo` also register `useQuery` and `useMutation`); everything else stays importable from the [subpath exports](https://nuxt-convex-module.dev/api-reference#subpath-exports). `false` auto-imports nothing.

</field>

<field name="authRoute" type="string" default="/api/auth">

Where the same-origin Better Auth proxy mounts. A missing leading `/` is added with a warning; a trailing `/` is stripped. Any other value needs your own `betterAuth.authClient` created with that `basePath` — the bundled client calls `/api/auth`, and the module errors at startup otherwise.

</field>

<field name="devtools" type="boolean" default="true">

The [Convex tab in Nuxt DevTools](https://nuxt-convex-module.dev/guide/devtools), dev only.

</field>

<field name="devScript" type="boolean" default="true">

On the first `nuxt dev` or `nuxt prepare`, rewrite a plain `nuxt dev` script to [`convex dev --start "nuxt dev"`](https://nuxt-convex-module.dev/getting-started/installation#run) so one command runs both. A script you have already changed is left alone; `false` never touches `package.json`.

</field>
</field-group>

## Runtime config

The module writes five keys into `runtimeConfig` at build time. Each is also a Nitro runtime override: set the variable where the built app starts — one image across environments — and it wins over the built-in value.

<field-group>
<field name="runtimeConfig.public.convex.url" type="string">

From `convex.url`, then `NUXT_PUBLIC_CONVEX_URL`, then `CONVEX_URL`. Runtime override: `NUXT_PUBLIC_CONVEX_URL`.

</field>

<field name="runtimeConfig.public.convex.siteUrl" type="string">

From `convex.siteUrl`, then `NUXT_PUBLIC_CONVEX_SITE_URL`, then `CONVEX_SITE_URL`. Runtime override: `NUXT_PUBLIC_CONVEX_SITE_URL`.

</field>

<field name="runtimeConfig.public.convex.crossDomainCallbackRoute" type="string">

From `convex.betterAuth.crossDomainCallbackRoute`. Runtime override: `NUXT_PUBLIC_CONVEX_CROSS_DOMAIN_CALLBACK_ROUTE`.

</field>

<field name="runtimeConfig.public.convex.loginPath" type="string">

From `convex.betterAuth.loginPath`. Runtime override: `NUXT_PUBLIC_CONVEX_LOGIN_PATH`.

</field>

<field name="runtimeConfig.convex.siteUrl" type="string">

Private; same source as the public `siteUrl`. Runtime override: `NUXT_CONVEX_SITE_URL`.

</field>
</field-group>

Trailing slashes are stripped from both URLs. With no deployment URL the module warns at startup and creates no client; see [troubleshooting](https://nuxt-convex-module.dev/getting-started/troubleshooting).

## Import aliases

The module registers ordered `#convex/*` aliases (for both Vite and Nitro) pointing at your Convex functions directory and its generated modules, so you never spell out `_generated`:

```ts
import { api } from '#convex/api'
import { query, mutation } from '#convex/server'
import type { Doc, Id } from '#convex/dataModel'
```

<table>
<thead>
  <tr>
    <th>
      Alias
    </th>
    
    <th>
      Resolves to
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        #convex/api
      </code>
    </td>
    
    <td>
      <code>
        _generated/api
      </code>
      
       (<code>
        api
      </code>
      
      , <code>
        internal
      </code>
      
      , <code>
        components
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        #convex/server
      </code>
    </td>
    
    <td>
      <code>
        _generated/server
      </code>
      
       (<code>
        query
      </code>
      
      , <code>
        mutation
      </code>
      
      , <code>
        action
      </code>
      
      , …)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        #convex/dataModel
      </code>
    </td>
    
    <td>
      <code>
        _generated/dataModel
      </code>
      
       (<code>
        DataModel
      </code>
      
      , <code>
        Doc
      </code>
      
      , <code>
        Id
      </code>
      
      , …)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        #convex/_generated
      </code>
    </td>
    
    <td>
      <code>
        _generated
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        #convex
      </code>
    </td>
    
    <td>
      your functions directory
    </td>
  </tr>
</tbody>
</table>

<note>

Order matters: the specific generated-module aliases are registered **before** the catch-all `#convex`, because the alias resolver is first-match-wins and `#convex` is a prefix of `#convex/api`.

</note>

The functions directory resolves in order: the `functions` field in `convex.json` (normalized — leading `./` and trailing slashes stripped), otherwise the `convex/` default. If `convex.json` fails to parse, the module warns and falls back to the `convex/` default.

You often don't need `#convex/api` at all: a generated plugin auto-provides the `api` app-wide, so namespace-reading composables and components (`<CheckoutLink>`, …) work with zero arguments.

### `#convex/auth-client`

Beyond `#convex/*`, the module registers one more alias (Vite + Nitro, always — even with Better Auth off, so type-checking resolves): it points at your `betterAuth.authClient` module when set (absolute, or relative to the project root), otherwise at the bundled Better Auth client. The Better Auth runtime (`useBetterAuth`, `<AuthBoundary>` typing, cross-domain helpers) resolves the client through this alias — see [bring your own auth client](https://nuxt-convex-module.dev/components/better-auth#bring-your-own-auth-client).

### Before codegen runs

`<functionsDir>/_generated/` (`convex/_generated/` by default) does not exist until the first `convex dev`. Until then:

- `#convex/api`, `#convex/server` and `#convex/dataModel` resolve to placeholder declarations typed `any` (`Id` stays `string`), so the project type-checks instead of failing on every import.
- The `api`-providing plugin is a no-op, so the features that read a namespace degrade to doing nothing.
- The dev log says `Convex codegen not found in convex/_generated — run npx convex dev`.

The module watches that directory. When codegen lands, the placeholders retire and the plugin picks up the real `api` without a restart — the log says `Convex codegen detected — generated api wired app-wide`.

## Client options

Under Nuxt the module creates the Convex client for you, with no options: both plugins call `new ConvexVueClient(url)`. `ConvexVueClientOptions` — `verbose`, `logger`, `unsavedChangesWarning`, `skipConvexDeploymentUrlCheck` and the rest — can't be set from `nuxt.config`. They are available where you construct the client yourself, in a [plain Vue app](https://nuxt-convex-module.dev/guide/plain-vue).

## Security (CSP)

[`nuxt-security`](https://nuxt-security.vercel.app) is an optional companion. Install it and the module detects it, registers it as a module dependency (no `modules` entry needed — if you list it yourself, Nuxt dedupes), and tightens a **Convex-aware Content Security Policy** on top of its defaults: in production `connect-src` allows your deployment — and, when `siteUrl` is configured, the `.site` origin — over both HTTPS and WebSocket, while `img-src` / `media-src` allow Convex-served storage from both origins.

<pm-install packages="nuxt-security">

```bash [pnpm]
pnpm add nuxt-security
```

```bash [npm]
npm i nuxt-security
```

```bash [yarn]
yarn add nuxt-security
```

```bash [bun]
bun add nuxt-security
```

</pm-install>

Your own directives are preserved — the Convex origins are appended. Opt out with `convex: { security: false }`; disabling nuxt-security itself (`security: false`) or its CSP (`security.headers.contentSecurityPolicy: false`) skips it as well. Configure everything else through the standard `security` key.

<note>

The CSP is one part of a larger picture — the hardened auth proxy, auth tokens in SSR payloads, safe post-sign-in redirects, and a production checklist all live on the [Security](https://nuxt-convex-module.dev/getting-started/security) page.

</note>


## Sitemap

See the full [sitemap](https://nuxt-convex-module.dev/sitemap.md) for all pages.