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.0or>=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.
pnpm create nuxt@latest my-convex-app
cd my-convex-app
pnpm approve-buildsPick 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
pnpm nuxi module add @lupinum/better-convex-nuxtThis 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:
{
"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.
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:
<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
pnpm devThe 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 generatesconvex/_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:
pnpm exec better-convex-nuxt convex dashboardYour project now looks like this:
my-convex-app/
├── app/
│ └── app.vue
├── convex/
│ ├── _generated/
│ └── tsconfig.json
├── .env.local
├── nuxt.config.ts
└── package.jsonThe 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:
pnpm exec better-convex-nuxt convex configureIt 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:
pnpm exec better-convex-nuxt --versionprints the installed version..env.localcontainsCONVEX_DEPLOYMENTandCONVEX_URL.convex/_generated/api.d.tsexists.- The
pnpm devoutput shows[convex] ✔ Convex functions ready!and the[nuxt]line withhttp://localhost:3000/.
If a check fails, see Troubleshooting.
Next, build a live page.