Skip to main content

Installation

Create a Nuxt app, add Better Convex Nuxt, and start Convex and Nuxt with one command.

This page creates a Nuxt app and starts it with a Convex backend on your computer. You need no Convex account. Authentication stays off until Add authentication. For Vue without Nuxt, use the plain Vue guide.

The finished app of this tutorial is in starters/tutorial. Compare your files with it when something does not work.

Prerequisites

  • Node.js ^22.22.3, ^24.15.0 or >=26.0.0
  • pnpm (npm and yarn also work; change the commands)

Create the Nuxt app

Skip this step if you already have a Nuxt 4.6 or newer app.

bash
pnpm create nuxt@latest my-convex-app
cd my-convex-app
pnpm approve-builds

Pick the minimal template when it asks. pnpm approve-builds lets pnpm run the build script of esbuild: select it and confirm. pnpm 10 and newer block build scripts until you allow them, and Nuxt does not start without this one.

Add the module

bash
pnpm nuxi module add @lupinum/better-convex-nuxt

This installs @lupinum/better-convex-nuxt and convex, and adds the module to modules in nuxt.config.ts. It prints a warning that no Convex deployment URL is configured. The next step fixes that.

Upgrading from a beta? Follow Upgrade to 1.0.

Use one dev command

In package.json, change the dev script:

package.json
{
  "scripts": {
    "dev": "better-convex-nuxt dev"
  }
}

Keep the other scripts. better-convex-nuxt dev runs convex dev and nuxt dev together. Each output line starts with [convex] or [nuxt]. Ctrl-C stops both.

The command is better-convex-nuxt. Do not run npx better-convex: that is an unrelated npm package.

Show the pages

The minimal template shows a welcome screen. Replace app/app.vue so that Nuxt renders your pages. The <style> block gives every page of this tutorial a simple layout:

app/app.vue
<template>
  <NuxtPage />
</template>

<style>
:root {
  color-scheme: light dark;
  font-family: system-ui, sans-serif;
}
main {
  max-width: 32rem;
  margin: 3rem auto;
  padding: 0 1rem;
}
form {
  display: flex;
  gap: 0.5rem;
  margin: 1rem 0;
}
form input {
  flex: 1;
  min-width: 0;
}
input,
button {
  padding: 0.5rem 0.75rem;
  font: inherit;
}
ul {
  padding: 0;
  list-style: none;
}
li {
  display: flex;
  gap: 0.75rem;
  align-items: center;
  padding: 0.5rem 0;
  border-bottom: 1px solid #8884;
}
li span {
  flex: 1;
  min-width: 0;
  /* A long word wraps instead of pushing Delete off-screen. */
  overflow-wrap: anywhere;
}
.done {
  text-decoration: line-through;
  opacity: 0.6;
}
.muted {
  opacity: 0.7;
}
.error {
  color: light-dark(#c00, #f77);
}
</style>

Start the app

bash
pnpm dev

The first start takes a minute. Convex downloads a backend for your computer and starts it. Then it:

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

When .env.local has the URL, Nuxt starts. Open http://localhost:3000. The page is empty because the app has no pages yet.

Do not commit .env.local. Later steps add secrets to it.

A local backend has a dashboard on your computer, where you can see your tables and logs. Open it with:

bash
pnpm exec better-convex-nuxt convex dashboard

Your project now looks like this:

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

The module adds the #convex/api alias for convex/_generated/api and auto-imports for useConvexQuery, useConvexMutation, and the other composables.

Use a Convex account instead

The local backend is enough for this tutorial. To use a deployment in your Convex account, stop pnpm dev and run:

bash
pnpm exec better-convex-nuxt convex configure

It asks you to sign in to Convex and to pick or create a project, and writes that deployment to .env.local. pnpm dev then uses it. All better-convex-nuxt commands read the deployment from .env.local only.

Check your setup

Run these checks when something does not work:

  1. pnpm exec better-convex-nuxt --version prints the installed version.
  2. .env.local contains CONVEX_DEPLOYMENT and CONVEX_URL.
  3. convex/_generated/api.d.ts exists.
  4. The pnpm dev output shows [convex] ✔ Convex functions ready! and the [nuxt] line with http://localhost:3000/.

If a check fails, see Troubleshooting.

Next, build a live page.