Installation

Install Better Convex Nuxt and verify the generated Convex API alias.

This setup creates a Nuxt 4 app with Convex and the module. Authentication stays disabled until the later auth step. For a client-only Vue/Vite application, use the plain Vue guide instead.

Prerequisites

Node.js 22.12+, 24.11+, or 26+
A Convex account
pnpm, npm, or another supported Node package manager

Create the applications

Create a Nuxt project if you do not already have one:

bash

pnpm create nuxt@latest my-convex-app
cd my-convex-app

Install Convex and the module:

bash

pnpm add convex better-convex-nuxt

This Convex-only install does not install Better Auth, the OAuth Provider, or a standalone Kysely peer. Add the exact optional auth peers only when enabling authentication.

Initialize Convex:

bash

pnpm exec better-convex-nuxt-convex configure

The Convex CLI connects or creates a deployment, writes its selection and public URLs to .env.local, creates convex/, and generates convex/_generated/api.

Keep that first command running while developing backend functions. On later runs, select only from the file it created:

bash

pnpm exec better-convex-nuxt-convex dev

Register the Nuxt module

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {},
})

Authentication is off because convex.auth is omitted. Add an explicit auth object only when you reach the authentication setup.

The module reads NUXT_PUBLIC_CONVEX_URL first and falls back to CONVEX_URL. Set the public name explicitly when your deployment platform does not expose the Convex CLI environment file during the Nuxt build:

.env.local

NUXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

Keep .env.local as the single ignored local configuration file. Nuxt defaults to .env, so invoke its CLI with --dotenv .env.local; do not create a sibling .env containing a second copy of deployment configuration. Production values belong in the hosting environment. Do not commit deployment credentials or auth secrets. A Convex deployment URL is public configuration; session tokens are not.

Prepare Nuxt types

bash

pnpm exec nuxt prepare --dotenv .env.local

The module registers:

#convex/api → your generated convex/_generated/api
#convex/server → the supported Nuxt server entry
client composable auto-imports
server helper auto-imports

Verify the API alias in a temporary component or page:

import { api } from '#convex/api'

console.log(api)

If TypeScript reports that convex/_generated/api is missing, run pnpm exec better-convex-nuxt-convex dev or pnpm exec better-convex-nuxt-convex codegen. The checked runner requires one explicit deployment selector in .env.local and removes inherited CONVEX_* authority before invoking the pinned Convex CLI.

Expected structure

my-convex-app/
├── app/
├── convex/
│   ├── _generated/
│   │   └── api.d.ts
│   └── tsconfig.json
├── .env.example
├── .env.local
├── nuxt.config.ts
└── package.json

Next, build the first real-time page.