---
title: "Installation"
description: "Install with your AI agent in one prompt, or by hand — add the module, run it, point it at a deployment, and add the optional packages later."
canonical_url: "https://nuxt-convex-module.dev/getting-started/installation"
---
# Installation
> Install with your AI agent in one prompt, or by hand — add the module, run it, point it at a deployment, and add the optional packages later.
## With an AI agent
Paste this prompt into Claude Code, Cursor, Codex or any agent that can run commands in your project:
```text
Install nuxt-convex-module, the Convex module for Nuxt, in this project:
run `npx skills add https://nuxt-convex-module.dev --skill nuxt-convex-module -y`,
then follow .agents/skills/nuxt-convex-module/references/install.md.
```
Or open it in your agent with the prompt typed in:
- Claude Code (Anthropic): [Claude app](claude://code/new?q=Install%20nuxt-convex-module%2C%20the%20Convex%20module%20for%20Nuxt%2C%20in%20this%20project%3A%0Arun%20%60npx%20skills%20add%20https%3A%2F%2Fnuxt-convex-module.dev%20--skill%20nuxt-convex-module%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-convex-module%2Freferences%2Finstall.md.), [VS Code](vscode://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Cursor](cursor://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Windsurf](windsurf://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Insiders](vscode-insiders://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [VSCodium](vscodium://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Kiro](kiro://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Antigravity](antigravity-ide://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Trae](trae://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Positron](positron://anthropic.claude-code/open?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Web](https://claude.ai/code?prompt=Install%20nuxt-convex-module%2C%20the%20Convex%20module%20for%20Nuxt%2C%20in%20this%20project%3A%0Arun%20%60npx%20skills%20add%20https%3A%2F%2Fnuxt-convex-module.dev%20--skill%20nuxt-convex-module%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-convex-module%2Freferences%2Finstall.md.)
- Cursor (Anysphere): [Cursor](cursor://anysphere.cursor-deeplink/prompt?text=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.)
- Codex (OpenAI): [Codex app](codex://new?prompt=Install%20nuxt-convex-module%2C%20the%20Convex%20module%20for%20Nuxt%2C%20in%20this%20project%3A%0Arun%20%60npx%20skills%20add%20https%3A%2F%2Fnuxt-convex-module.dev%20--skill%20nuxt-convex-module%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-convex-module%2Freferences%2Finstall.md.)
- Copilot (GitHub): [VS Code](vscode://GitHub.Copilot-Chat/chat?mode=agent&prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.), [Insiders](vscode-insiders://GitHub.Copilot-Chat/chat?mode=agent&prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.)
- Cascade (Cognition): [Windsurf](windsurf://cascade?prompt=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.)
- Zed (Zed Industries): [Zed](zed://agent?prompt=Install%20nuxt-convex-module%2C%20the%20Convex%20module%20for%20Nuxt%2C%20in%20this%20project%3A%0Arun%20%60npx%20skills%20add%20https%3A%2F%2Fnuxt-convex-module.dev%20--skill%20nuxt-convex-module%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-convex-module%2Freferences%2Finstall.md.)
- Trae (ByteDance): [Trae](trae://trae.ai-ide/side-chat?query=Install%2520nuxt-convex-module%252C%2520the%2520Convex%2520module%2520for%2520Nuxt%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520skills%2520add%2520https%253A%252F%252Fnuxt-convex-module.dev%2520--skill%2520nuxt-convex-module%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-convex-module%252Freferences%252Finstall.md.)
The agent installs the module's [skill](https://nuxt-convex-module.dev/getting-started/ai-agents#agent-skill), then follows its install guide. The guide adds the module to an existing app (or creates one from the starter), creates a local Convex deployment that needs no account, generates the code, and checks that the dev server runs. It asks before logging in to Convex or creating anything in your account. The skill stays in the project for later tasks.
## By hand
Starting a new app? This creates one from the [starter](https://nuxt-convex-module.dev/getting-started/templates) with the module already installed, so you can go straight to [Run](#run):
```bash [pnpm]
pnpm create nuxt@latest my-app -t gh:qruto/nuxt-convex-module/templates/starter
```
```bash [npm]
npm create nuxt@latest my-app -- -t gh:qruto/nuxt-convex-module/templates/starter
```
```bash [yarn]
yarn create nuxt my-app -t gh:qruto/nuxt-convex-module/templates/starter
```
```bash [bun]
bun create nuxt@latest my-app --template=gh:qruto/nuxt-convex-module/templates/starter
```
### Add the module
Add `convex` — the package your functions in `convex/` import from, and a peer of the module — then let `nuxi` install and register the module:
```bash [pnpm]
pnpm add convex
```
```bash [npm]
npm i convex
```
```bash [yarn]
yarn add convex
```
```bash [bun]
bun add convex
```
```bash [pnpm]
pnpm dlx nuxi@latest module add nuxt-convex-module
```
```bash [npm]
npx nuxi@latest module add nuxt-convex-module
```
```bash [yarn]
yarn dlx nuxi@latest module add nuxt-convex-module
```
```bash [bun]
bunx nuxi@latest module add nuxt-convex-module
```
If you would rather add the package yourself, install it and list the module:
```bash [pnpm]
pnpm add nuxt-convex-module convex
```
```bash [npm]
npm i nuxt-convex-module convex
```
```bash [yarn]
yarn add nuxt-convex-module convex
```
```bash [bun]
bun add nuxt-convex-module convex
```
```ts [nuxt.config.ts]
export default defineNuxtConfig({
modules: ['nuxt-convex-module'],
})
```
That is the whole setup: composables, components and server helpers are auto-imported.
Using **strict** pnpm? Set `publicHoistPattern: ['@convex-dev/*']` in `pnpm-workspace.yaml` (`public-hoist-pattern[]=@convex-dev/*` in `.npmrc` on pnpm 9, or `nodeLinker: hoisted`) so Convex can resolve component definitions.
On pnpm 11 and later, `nuxi module add` can stop with `ERR_PNPM_IGNORED_BUILDS` (usually for `esbuild`, which Nuxt itself brings) and leave `nuxt.config.ts` unchanged. Allow or deny those build scripts — `pnpm approve-builds`, or `allowBuilds` in `pnpm-workspace.yaml` — and run it again.
### Run
One command runs Convex and Nuxt together:
```bash [pnpm]
pnpm dev
```
```bash [npm]
npm run dev
```
```bash [yarn]
yarn dev
```
```bash [bun]
bun run dev
```
The first time the module runs it rewrites a plain `nuxt dev` script to `convex dev --start "nuxt dev"`: the Convex CLI creates or attaches your dev deployment, writes its `CONVEX_URL` and `CONVEX_SITE_URL` to `.env.local`, and starts Nuxt beside it. If the rewrite happens inside a running `nuxt dev`, that process is still plain Nuxt, so stop it and run `dev` again. The module reads `.env.local` in development, so there is nothing to put in `.env`. A `dev` script you have already changed is left alone; [`convex.devScript: false`](https://nuxt-convex-module.dev/getting-started/configuration#module-options-convex) keeps `package.json` untouched.
Read live data with [`useQuery`](https://nuxt-convex-module.dev/guide/queries), write with [`useMutation`](https://nuxt-convex-module.dev/guide/mutations-and-actions), import your functions from [`#convex/api`](https://nuxt-convex-module.dev/getting-started/configuration#import-aliases).
Until that first run has written `_generated/` into your functions directory (`convex/` by default), the `#convex/*` imports are typed `any` and the `api`-providing plugin is a no-op; the dev log says so. Nothing to restart — the module picks the generated files up when they appear. Details under [before codegen runs](https://nuxt-convex-module.dev/getting-started/configuration#before-codegen-runs).
### Point it at the deployment you ship
```dotenv [.env]
NUXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NUXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
```
The module reads these at build time from `.env`, the file Nuxt loads on its own, and `NUXT_PUBLIC_CONVEX_URL` is also the runtime override on a built app — one image across environments.
The `.env.local` that `convex dev` writes holds your *dev* deployment, and only `nuxt dev` reads it: a build takes its URL from `convex.url` or these variables. Set in the environment, the `NUXT_PUBLIC_` names win over `.env.local` in development too.
### Optional: add what you need
Auth, billing and security headers are opt-in. Skip this step until you need one; installing the package is the whole wiring — no extra `modules` entries. The Better Auth and Polar packages are pinned to the minor versions the module supports: without the pin, pnpm, yarn and bun install the newest release whatever the [supported range](#requirements) says.
**Better Auth** — sessions, sign-in flows, an `/api/auth/**` proxy and the `convex-auth` middleware ([docs](https://nuxt-convex-module.dev/components/better-auth)):
```bash [pnpm]
pnpm add @convex-dev/better-auth@~0.12.0 better-auth@~1.6.11
```
```bash [npm]
npm i @convex-dev/better-auth@~0.12.0 better-auth@~1.6.11
```
```bash [yarn]
yarn add @convex-dev/better-auth@~0.12.0 better-auth@~1.6.11
```
```bash [bun]
bun add @convex-dev/better-auth@~0.12.0 better-auth@~1.6.11
```
**Clerk** ([docs](https://nuxt-convex-module.dev/components/clerk)):
```bash [pnpm]
pnpm add @clerk/vue
```
```bash [npm]
npm i @clerk/vue
```
```bash [yarn]
yarn add @clerk/vue
```
```bash [bun]
bun add @clerk/vue
```
**Auth0** ([docs](https://nuxt-convex-module.dev/components/auth0)):
```bash [pnpm]
pnpm add @auth0/auth0-vue
```
```bash [npm]
npm i @auth0/auth0-vue
```
```bash [yarn]
yarn add @auth0/auth0-vue
```
```bash [bun]
bun add @auth0/auth0-vue
```
**Polar billing** ([docs](https://nuxt-convex-module.dev/components/polar)):
```bash [pnpm]
pnpm add @convex-dev/polar@~0.9.0 @polar-sh/checkout
```
```bash [npm]
npm i @convex-dev/polar@~0.9.0 @polar-sh/checkout
```
```bash [yarn]
yarn add @convex-dev/polar@~0.9.0 @polar-sh/checkout
```
```bash [bun]
bun add @convex-dev/polar@~0.9.0 @polar-sh/checkout
```
**Security headers** — a CSP that knows your deployment's origins ([docs](https://nuxt-convex-module.dev/getting-started/security)):
```bash [pnpm]
pnpm add nuxt-security
```
```bash [npm]
npm i nuxt-security
```
```bash [yarn]
yarn add nuxt-security
```
```bash [bun]
bun add nuxt-security
```
How each one switches itself on, and how to force it on or off, is in [Components](https://nuxt-convex-module.dev/components).
## Requirements
**Nuxt >= 4.1.0** and **Node >= 24.11.0**. The peer ranges below are what you may install; every one but `vue` and `convex` is optional, needed only by the integration it powers. Floors are raised only in a major release.
|
Package
|
Range
|
vue
|
^3.5.0
|
convex
|
^1.46.0
|
@convex-dev/better-auth
|
>=0.12.0 <0.13.0
|
better-auth
|
~1.6.11
|
@convex-dev/polar
|
>=0.9.0 <0.10.0
|
@polar-sh/checkout
|
>=0.4.0
|
@clerk/vue
|
>=2.0.0
|
@auth0/auth0-vue
|
>=2.0.0
|
nuxt-security
|
>=2.6.0
|
The exact upstream releases the port is diffed against are narrower and stated per package: [Convex](https://nuxt-convex-module.dev/getting-started/introduction#coming-from-convex-react), and each [component](https://nuxt-convex-module.dev/components) page.
## Sitemap
See the full [sitemap](https://nuxt-convex-module.dev/sitemap.md) for all pages.