Installation

Create a Nuxt app, install Better Convex Nuxt, and connect a Convex deployment.

This page creates a Nuxt 4 app and connects it to Convex. Authentication stays off until Add authentication. For Vue without Nuxt, use the plain Vue guide.

Prerequisites

Node.js ^22.19.0 or ^24.11.0
A Convex account
pnpm (npm and yarn also work; change the commands)

Create the Nuxt app

Skip this step if you already have a Nuxt 4 app.

bash

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

Install the packages

bash

pnpm add @lupinum/better-convex-nuxt@next convex@^1.42.2

The next dist-tag is the 1.0 release candidate. Upgrading from a beta? Follow Upgrade to 1.0.

The module needs these versions:

Package	Version
`nuxt`	`>=4.5.2 <5`
`convex`	`>=1.42.2 <2`

Check that nuxt in your package.json is 4.5.2 or newer. Better Auth is not installed yet. You add it in the auth step.

Connect a Convex deployment

bash

pnpm exec better-convex convex configure

The command asks you to sign in to Convex and to pick or create a project. It then:

writes the deployment name and URLs to .env.local;
creates the convex/ folder;
generates convex/_generated/api;
keeps running and uploads your Convex functions on every save.

Keep this terminal open while you work. Next time, start it with:

bash

pnpm exec better-convex convex dev

All better-convex convex commands read the deployment from .env.local only. Keep all local settings in that one file. Do not create a second .env file.

Register the module

nuxt.config.ts

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

The module reads the Convex URL from NUXT_PUBLIC_CONVEX_URL or CONVEX_URL. The Convex command usually writes CONVEX_URL to .env.local. If it wrote VITE_CONVEX_URL instead, or on a hosting platform, set NUXT_PUBLIC_CONVEX_URL:

.env.local

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

The Convex URL is public. Do not commit .env.local anyway, because later steps add secrets to it.

Show the pages

The default Nuxt template shows a welcome screen. Replace app/app.vue so that Nuxt renders your pages:

app/app.vue

<template>
  <NuxtPage />
</template>

Generate the types

bash

pnpm exec nuxt prepare --dotenv .env.local

Always pass --dotenv .env.local to Nuxt commands, so Nuxt reads the same file as Convex.

The module adds:

the #convex/api alias for convex/_generated/api;
auto-imports for useConvexQuery, useConvexMutation, and the other composables;
the #convex/server alias and auto-imports for Nuxt server routes.

If TypeScript cannot find convex/_generated/api, check that better-convex convex dev is running. You can also run pnpm exec better-convex convex codegen.

Your project now looks like this:

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

Next, build a live page.