---
title: "Module Configuration"
description: "Every option of the convex key in nuxt.config.ts, how the deployment URL is resolved, and what ends up in runtimeConfig."
canonical_url: "https://nuxt-convex.onmax.me/api-reference/module-configuration"
---
# Module Configuration

> Every option of the convex key in nuxt.config.ts, how the deployment URL is resolved, and what ends up in runtimeConfig.

Configure `nuxt-convex` with the `convex` key in `nuxt.config.ts`. Every option is optional: with a `CONVEX_URL` in the environment, `modules: ['nuxt-convex']` is a working setup.

`nuxt-convex` supports Nuxt `>=4.6.0 <6.0.0`.

## Example

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['nuxt-convex'],
  convex: {
    url: 'https://happy-otter-123.convex.cloud',
    ssr: true,
    storage: true,
    clientOptions: {
      unsavedChangesWarning: false,
    },
    auth: {
      provider: 'better-auth',
      basePath: '/api/auth',
    },
  },
})
```

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      from env
    </td>
    
    <td>
      Convex deployment URL. See <a href="#url-resolution">
        URL resolution
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        siteUrl
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      from env, else derived
    </td>
    
    <td>
      HTTP actions URL (<code>
        https://<name>.convex.site
      </code>
      
      ). Used by the Better Auth proxy.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dir
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        'convex'
      </code>
    </td>
    
    <td>
      Convex source directory. Relative paths are resolved across Nuxt layers.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ssr
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Default for running awaited queries during SSR. Each query can override it with its <code>
        server
      </code>
      
       option.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Deprecated name of <code>
        ssr
      </code>
      
      . Still works and logs a deprecation warning.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        storage
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Adds <code>
        #convex/storage
      </code>
      
      , the storage auto-imports, and scaffolds <code>
        convex/_hub/storage.ts
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        r2
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Adds the <code>
        useConvexR2Upload
      </code>
      
       auto-import.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clientOptions
      </code>
    </td>
    
    <td>
      <code>
        ConvexClientConfig
      </code>
    </td>
    
    <td>
      <code>
        {}
      </code>
    </td>
    
    <td>
      Options for the browser <code>
        ConvexClient
      </code>
      
      . See <a href="#client-options">
        Client options
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auth
      </code>
    </td>
    
    <td>
      <code>
        boolean | ConvexAuthConfig
      </code>
    </td>
    
    <td>
      see below
    </td>
    
    <td>
      Token provider for SSR and server routes, and the Better Auth proxy. See <a href="#auth">
        Auth
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        devtools
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Adds a Convex tab to Nuxt DevTools in development.
    </td>
  </tr>
</tbody>
</table>

### `ssr` and `server`

The module option is `ssr`, like the top-level `ssr` in `nuxt.config.ts`: it sets the default for the whole app. The per-query option is `server`, like `useFetch(url, { server: false })`: it overrides that default for one call.

```ts
// Never runs during SSR, even with `convex.ssr: true`
const { data } = await useConvexQuery(api.tasks.list, {}, { server: false })
```

See [SSR & Hydration](https://nuxt-convex.onmax.me/nuxt-module/ssr-and-hydration) for what each combination does.

## URL resolution

At build time, the first value found wins:

1. `convex.url` in `nuxt.config.ts`
2. `CONVEX_URL`
3. `NUXT_PUBLIC_CONVEX_URL`
4. `VITE_CONVEX_URL`
5. `.env.local`, in development only (`npx convex dev` writes it, and Nuxt doesn't load it by itself)

`siteUrl` resolves the same way from `convex.siteUrl`, `CONVEX_SITE_URL`, `NUXT_PUBLIC_CONVEX_SITE_URL`, `VITE_CONVEX_SITE_URL` and `.env.local`. When none is set it's derived from the deployment URL at runtime: `https://x.convex.cloud` becomes `https://x.convex.site`, and a local backend's port goes up by one (`3210` becomes `3211`).

At runtime, `NUXT_PUBLIC_CONVEX_URL` and `NUXT_PUBLIC_CONVEX_SITE_URL` override the built values, so one build can point at different deployments. If you override the URL at runtime and baked a `siteUrl` into the build, override the site URL too.

Without a URL, the app starts disconnected: queries stay pending, and the module warns in development. On Nuxt 5, a production build without a URL needs `NUXT_PUBLIC_CONVEX_URL` to start the server. See [Runtime config](#runtime-config).

See [Local Development](https://nuxt-convex.onmax.me/getting-started/local-development) for the full picture of where these variables come from.

## Client options

`clientOptions` is passed to the browser `ConvexClient`. Only JSON-serializable options are accepted, because they travel through `runtimeConfig`:

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        verbose
      </code>
    </td>
    
    <td>
      Log client activity to the console
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logger
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
      
       silences the client's console logging
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unsavedChangesWarning
      </code>
    </td>
    
    <td>
      Warn before closing the tab while a mutation is in flight. On by default in browsers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skipConvexDeploymentUrlCheck
      </code>
    </td>
    
    <td>
      Skip the client's check that the URL looks like a Convex Cloud deployment, for self-hosted backends. Also applied to the server's HTTP client
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        authRefreshTokenLeewaySeconds
      </code>
    </td>
    
    <td>
      How long before expiry the client refreshes its token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        expectAuth
      </code>
    </td>
    
    <td>
      Hold queries until a token is set. The module turns it on by itself when SSR rendered a signed-in user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reportDebugInfoToConvex
      </code>
    </td>
    
    <td>
      Send client debug info to Convex
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        initialAuthTokenReuse
      </code>
    </td>
    
    <td>
      Reuse the cached token after it's confirmed instead of fetching a fresh one
    </td>
  </tr>
</tbody>
</table>

For a custom logger object, or anything that isn't serializable, configure the client yourself through [`#convex/advanced`](https://nuxt-convex.onmax.me/api-reference/use-convex-controller).

## Auth

```ts
interface ConvexAuthConfig {
  provider?: 'better-auth' | false
  basePath?: string
  proxy?: boolean
}
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      <code>
        'better-auth'
      </code>
      
       when <code>
        @nuxtjs/better-auth
      </code>
      
       is installed, else <code>
        false
      </code>
    </td>
    
    <td>
      Built-in token provider. <code>
        'better-auth'
      </code>
      
       exchanges the Better Auth session cookie for a Convex JWT. With <code>
        false
      </code>
      
      , tokens come only from the <a href="https://nuxt-convex.onmax.me/nuxt-module/authenticated-ssr#custom-providers">
        <code>
          convex:token
        </code>
        
         hook
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        basePath
      </code>
    </td>
    
    <td>
      <code>
        '/api/auth'
      </code>
    </td>
    
    <td>
      Better Auth base path. The token is read from <code>
        <basePath>/convex/token
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        proxy
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       with the <code>
        better-auth
      </code>
      
       provider
    </td>
    
    <td>
      Proxies <code>
        <basePath>/**
      </code>
      
       to the Convex site URL, where Better Auth runs as a Convex component. Defaults to <code>
        false
      </code>
      
       when <code>
        @nuxtjs/better-auth
      </code>
      
       runs its own server (<code>
        auth.clientOnly: false
      </code>
      
      ).
    </td>
  </tr>
</tbody>
</table>

`auth: true` is the same as leaving it out. `auth: false` turns off the built-in provider, the proxy and the Better Auth client plugin; the `convex:token` hook keeps working.

With `@nuxtjs/better-auth` installed, setting its `auth.database.provider` to `'convex'` fails the build: that provider was removed. See [Better Auth](https://nuxt-convex.onmax.me/integrations/better-auth) for the supported setup.

## What the module adds

The public Nuxt alias matrix is `#convex`, `#convex/api`, `#convex/advanced`, with optional `#convex/storage` when storage is enabled. Server code also gets `#convex/server`.

Always:

- `#convex`, `#convex/api` and `#convex/advanced`
- `#convex/server` in Nitro (server routes, middleware and plugins)
- auto-imports for `useConvexQuery`, `useConvexQueries`, `useConvexMutation`, `useConvexAction`, `useConvexPaginatedQuery`, `useConvexAuth` and `useConvexConnectionState`
- server auto-imports for `useConvexServer`, `serverConvexQuery`, `serverConvexMutation`, `serverConvexAction`, `getConvexToken`, `requireConvexAuth` and `toConvexH3Error` (Nitro 2 only, see [Server Routes](https://nuxt-convex.onmax.me/nuxt-module/server-routes))
- the components `ConvexQuery`, `ConvexPaginatedQuery`, `ConvexAuthenticated`, `ConvexUnauthenticated` and `ConvexAuthLoading`. They're registered as Nuxt components, so they're auto-imported where you use them and left out of pages that don't
- a server middleware that resolves the request's Convex token on demand
- the Better Auth proxy route, when `auth.proxy` is on

With `storage: true`:

- `#convex/storage`
- auto-imports for `useConvexStorage` and `useConvexUpload`
- `convex/_hub/storage.ts`, scaffolded if missing

With `r2: true`:

- the `useConvexR2Upload` auto-import

The module does not create an R2-specific alias.

In development, the module also watches for `convex/_generated/` to appear (so starting `npx convex dev` after `nuxt dev` needs no restart) and, with `devtools` on, adds a DevTools tab that links to your deployment in the Convex dashboard.

## Runtime config

The resolved options are written to `runtimeConfig.public.convex`:

```ts
interface ConvexPublicRuntimeConfig {
  url: string
  siteUrl: string
  ssr: boolean
  storage: boolean
  r2: boolean
  clientOptions: ConvexClientConfig
  auth: {
    provider: 'better-auth' | 'none'
    basePath: string
    proxy: boolean
  }
}
```

Values you set yourself under `runtimeConfig.public.convex` take precedence over the module's.

On Nuxt 5, the module also registers a schema for these values, so Nuxt checks them when the server starts, converts `NUXT_PUBLIC_CONVEX_*` variables to the right type, and types `useRuntimeConfig().public.convex`. For example, `NUXT_PUBLIC_CONVEX_SSR=off` becomes `false`, `NUXT_PUBLIC_CONVEX_CLIENT_OPTIONS_AUTH_REFRESH_TOKEN_LEEWAY_SECONDS=30` becomes `30`, and `NUXT_PUBLIC_CONVEX_AUTH_PROVIDER=clerk` stops the server. If the build had no URL, the server refuses to start until `NUXT_PUBLIC_CONVEX_URL` is set. `nuxt dev` still starts without one, so you can run `npx convex dev` afterwards. Nuxt 4 applies the variables as before, without these checks.

## Related pages

- [Virtual Modules](https://nuxt-convex.onmax.me/api-reference/virtual-modules)
- [Local Development](https://nuxt-convex.onmax.me/getting-started/local-development)
- [Authenticated SSR](https://nuxt-convex.onmax.me/nuxt-module/authenticated-ssr)


## Sitemap

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