--- title: "Installation" description: "Install nuxt-backend with your coding agent in one prompt, or by hand — add the Nuxt module, configure environment variables, scaffold the Convex files, and start Convex." canonical_url: "https://nuxt-backend.dev/docs/start/installation" --- # Installation > Install nuxt-backend with your coding agent in one prompt, or by hand — add the Nuxt module, configure environment variables, scaffold the Convex files, and start Convex. ## 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-backend, the all-in-one SaaS backend for Nuxt on Convex, in this project: run `npx -y skills@1.7.0 add https://nuxt-backend.dev --skill nuxt-backend -y`, then follow .agents/skills/nuxt-backend/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-backend%2C%20the%20all-in-one%20SaaS%20backend%20for%20Nuxt%20on%20Convex%2C%20in%20this%20project%3A%0Arun%20%60npx%20-y%20skills%401.7.0%20add%20https%3A%2F%2Fnuxt-backend.dev%20--skill%20nuxt-backend%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-backend%2Freferences%2Finstall.md.), [VS Code](vscode://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Cursor](cursor://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Windsurf](windsurf://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Insiders](vscode-insiders://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [VSCodium](vscodium://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Kiro](kiro://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Antigravity](antigravity-ide://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Trae](trae://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Positron](positron://anthropic.claude-code/open?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Web](https://claude.ai/code?prompt=Install%20nuxt-backend%2C%20the%20all-in-one%20SaaS%20backend%20for%20Nuxt%20on%20Convex%2C%20in%20this%20project%3A%0Arun%20%60npx%20-y%20skills%401.7.0%20add%20https%3A%2F%2Fnuxt-backend.dev%20--skill%20nuxt-backend%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-backend%2Freferences%2Finstall.md.) - Cursor (Anysphere): [Cursor](cursor://anysphere.cursor-deeplink/prompt?text=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.) - Codex (OpenAI): [Codex app](codex://new?prompt=Install%20nuxt-backend%2C%20the%20all-in-one%20SaaS%20backend%20for%20Nuxt%20on%20Convex%2C%20in%20this%20project%3A%0Arun%20%60npx%20-y%20skills%401.7.0%20add%20https%3A%2F%2Fnuxt-backend.dev%20--skill%20nuxt-backend%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-backend%2Freferences%2Finstall.md.) - Copilot (GitHub): [VS Code](vscode://GitHub.Copilot-Chat/chat?mode=agent&prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.), [Insiders](vscode-insiders://GitHub.Copilot-Chat/chat?mode=agent&prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.) - Cascade (Cognition): [Windsurf](windsurf://cascade?prompt=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.) - Zed (Zed Industries): [Zed](zed://agent?prompt=Install%20nuxt-backend%2C%20the%20all-in-one%20SaaS%20backend%20for%20Nuxt%20on%20Convex%2C%20in%20this%20project%3A%0Arun%20%60npx%20-y%20skills%401.7.0%20add%20https%3A%2F%2Fnuxt-backend.dev%20--skill%20nuxt-backend%20-y%60%2C%0Athen%20follow%20.agents%2Fskills%2Fnuxt-backend%2Freferences%2Finstall.md.) - Trae (ByteDance): [Trae](trae://trae.ai-ide/side-chat?query=Install%2520nuxt-backend%252C%2520the%2520all-in-one%2520SaaS%2520backend%2520for%2520Nuxt%2520on%2520Convex%252C%2520in%2520this%2520project%253A%250Arun%2520%2560npx%2520-y%2520skills%25401.7.0%2520add%2520https%253A%252F%252Fnuxt-backend.dev%2520--skill%2520nuxt-backend%2520-y%2560%252C%250Athen%2520follow%2520.agents%252Fskills%252Fnuxt-backend%252Freferences%252Finstall.md.) The agent installs the package's [skill](https://nuxt-backend.dev/docs/agents/coding#the-agent-skill), then follows its install guide. The guide adds the package to an existing app (or creates one from the [starter](https://nuxt-backend.dev/docs/start/templates#starter)), starts it on a local Convex deployment that needs no account, and checks that the app serves `/login`. It asks before it logs in to Convex or touches your accounts, and it never prints or replaces `AUTH_SECRET`. The skill stays in the project for later tasks. The rest of this page is the same install by hand. ## Prerequisites - **Nuxt ≥ 4.1** — the module's declared compatibility (`^4.1.0`: it relies on module dependencies with option forwarding, a 4.1 feature, and its server handlers are written for Nuxt 4's Nitro 2, so Nuxt 5 is not supported yet). - **Node ≥ 24.11** — the package's `engines` floor. - A [Convex](https://convex.dev) deployment (`npx convex dev` creates one). - A package manager. The bundled Convex components ship as dependencies of `nuxt-backend`; the only other package you add is `convex` itself — its peer, and the CLI you run. ### Install the package ```bash [nuxt] npx nuxt module add nuxt-backend npm install convex ``` ```bash [pnpm] pnpm add nuxt-backend convex ``` ```bash [npm] npm install nuxt-backend convex ``` ```bash [yarn] yarn add nuxt-backend convex ``` The bundled components (`@convex-dev/aggregate`, `migrations`, `polar`, `rate-limiter`, `resend`, `workflow`, `better-auth`) come in transitively — you never add them to your own `package.json`. `convex` is the one peer you declare yourself: a package manager installs it either way, but `npx convex dev` reads your `package.json` and refuses to run until it is listed there (`npx nuxt-backend init` adds it when missing). Strict pnpm needs one extra line; see the note below. ### Add the Nuxt module ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['nuxt-backend'], }) ``` In a fresh `create nuxt` app, `app/app.vue` still renders `` and no `` — the pages this module registers (`/login`, `/pricing`, …) resolve but never render. Replace `` with `` (`npx nuxt-backend init` does it while the file is still the starter; the dev console warns while it is not done). ### Configure environment variables `npx nuxt-backend init` writes a `.env.example` grouped by what each value is for — copy it to `.env.local`. Nothing in it is required in dev: the backend URLs derive from the deployment slug the platform CLI writes, and `AUTH_SECRET` + `SITE_URL` are provisioned for you on the first run. ```bash [.env.local] # ── Backend ────────────────────────────────────────────────────────────────── # Normally derived. Set these only to point at another deployment. # NUXT_PUBLIC_BACKEND_URL= # NUXT_PUBLIC_BACKEND_SITE_URL= # ── Email ──────────────────────────────────────────────────────────────────── # Unset: sends no-op and OTP codes print in the backend dev console. # EMAIL_API_KEY= # EMAIL_FROM= # EMAIL_TEST_MODE= # EMAIL_WEBHOOK_SECRET= # ── Billing ────────────────────────────────────────────────────────────────── # Unset: billing reads return empty and checkout fails on invocation. # BILLING_ACCESS_TOKEN= # BILLING_ENVIRONMENT= # BILLING_WEBHOOK_SECRET= # ── Dev only ───────────────────────────────────────────────────────────────── # Also trust the http://localhost:* origin the dev server runs on, in addition # to SITE_URL. `env push` forwards this to dev deployments, never to production. # AUTH_TRUST_LOCAL_ORIGINS=1 ``` `npx convex dev` appends its own two lines to `.env.local` after those groups — a `# Deployment used by `npx convex dev`` comment and `CONVEX_DEPLOYMENT=dev:`. They belong to the platform CLI — leave them alone. #### Deployment environment The `EMAIL_*` and `BILLING_*` values live on the Convex **deployment**, not in the Nuxt process — `npm run dev` (or `npx nuxt-backend env push`) forwards whatever `.env.local` holds. To set them by hand, via the CLI or the [dashboard](https://dashboard.convex.dev). A secret left off the command line is asked for at a hidden prompt, or read from a pipe, so it never lands in your shell history: ```bash # required — a deploy fails without these two openssl rand -base64 32 | npx convex env set AUTH_SECRET npx convex env set SITE_URL https://nuxt-backend.localhost # optional — email (powered by Resend) npx convex env set EMAIL_API_KEY # asks for the key npx convex env set EMAIL_FROM "Acme " npx convex env set EMAIL_TEST_MODE true npx convex env set EMAIL_WEBHOOK_SECRET # asks for the secret # optional — billing (powered by Polar) npx convex env set BILLING_ACCESS_TOKEN # asks for the token npx convex env set BILLING_WEBHOOK_SECRET # asks for the secret npx convex env set BILLING_ENVIRONMENT sandbox # or production ``` So the values split like this:
Location Variables
.env.local (Nuxt app) NUXT_PUBLIC_BACKEND_URL , NUXT_PUBLIC_BACKEND_SITE_URL — both normally derived, so usually nothing
Convex deployment Required: AUTH_SECRET , SITE_URL . Optional: EMAIL_API_KEY , EMAIL_FROM , EMAIL_TEST_MODE , EMAIL_WEBHOOK_SECRET , BILLING_ACCESS_TOKEN , BILLING_WEBHOOK_SECRET , BILLING_ENVIRONMENT , and AUTH_TRUST_LOCAL_ORIGINS on a dev deployment
`AUTH_SECRET` and `SITE_URL` are **required** — a Convex deploy fails until both are set, so misconfiguration surfaces at push time instead of as a silent no-op in production. Everything else is optional and degrades in a designed, observable way until you configure it (`npx nuxt-backend doctor` reports each). See the [configuration reference](https://nuxt-backend.dev/docs/reference/configuration/environment-variables#convex-deployment-variables) for what each variable does. ### Start the app once to scaffold the backend ```bash npm run dev ``` On first run the module creates the Convex files that mount the packaged components, register the webhook routes, and re-export each feature's functions. If a Convex functions directory already exists it is reused; otherwise `backend/` is created: ```text your-project/ ├── backend/ │ ├── convex.config.ts # defineApp + one app.use per component — mounts everything │ ├── auth.config.ts │ ├── auth.ts # setupAuth — passwordless auth + workspaces │ ├── http.ts # registerBackendRoutes — auth + webhook routes │ ├── functions.ts # authorization + pre-authorized builders │ ├── billing.ts # setupBilling — subscriptions, credits, gifts │ ├── billing.catalog.ts # defineBillingCatalog — meters, plans, packs (ships commented out) │ ├── billing.generated.ts # the provider id map `billing sync` writes — do not edit │ ├── ai.ts # setupAi — metered actions and streams │ ├── email.ts # setupEmail — transactional + marketing email │ ├── rateLimiter.ts │ ├── workflows.ts │ ├── migrations.ts │ ├── aggregates.ts │ └── search.ts └── convex.json ``` `convex.json` is only generated when the functions directory is non-standard (anything other than `convex/`). ### Start Convex and Nuxt ```bash npx nuxt-backend dev ``` It sets up a dev deployment on the first run, provisions its env, then runs Convex beside Nuxt; see [`dev`](https://nuxt-backend.dev/docs/reference/cli#dev). `npx nuxt-backend init` points your `dev` script at it. Deploy with `npx convex deploy`. ## Optional: override module defaults Most apps do not need a `backend` block. Add it only to override the env-based defaults or change the auth route: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['nuxt-backend'], backend: { url: 'https://your-deployment.convex.cloud', siteUrl: 'https://your-deployment.convex.site', authRoute: '/api/auth', }, }) ``` ## Using strict pnpm A flat `node_modules` (npm, yarn, or pnpm with `nodeLinker: hoisted`) exposes the bundled components automatically. pnpm's default isolated linker hides transitive deps, so let Convex's components reach the project root from `pnpm-workspace.yaml` (pnpm 11+ reads its settings there, not from `.npmrc`): ```yaml [pnpm-workspace.yaml] publicHoistPattern: - '@convex-dev/*' ``` (or set `nodeLinker: hoisted`). Without this, the `convex dev` push fails to resolve the component definitions. The Nuxt side needs nothing: `nuxt-convex-module`, `nuxt-security` and the MCP toolkit are installed by the module from its own dependency tree. Apps created from the [templates](https://nuxt-backend.dev/docs/start/templates) carry this setting and the build-script answers below in a `.pnpmfile.mjs`, so they install under strict pnpm as they are. pnpm 11 also refuses to install any version published less than 24 hours ago (`minimumReleaseAge`) and stops an install until every dependency build script is approved or denied (`pnpm approve-builds`). `esbuild` comes in through Nuxt and works without its script, so denying it is safe. Both are pnpm's own supply-chain defaults, not this package's. The scaffolded `convex.config.ts` imports every component definition directly — the all-in-one `backend` component from `nuxt-backend/convex.config` plus the six upstream `@convex-dev/*/convex.config` modules (the seventh, `resend`, is imported inside the `backend` component) — and Convex builds its component tree from those imports. The `@convex-dev/*` packages therefore must be resolvable from your project root, hence the hoist pattern. You never add them to your own `package.json`. ## Upgrading Every release lists what changed, and what a change asks of you, on the [GitHub Releases](https://github.com/qruto/nuxt-backend/releases) page — the same notes ship in the package's `CHANGELOG.md`. Which parts of the package a version number promises to keep, and how upstream releases map onto ours, is [STABILITY.md](https://github.com/qruto/nuxt-backend/blob/main/STABILITY.md). On npm, `0.1.0` was a throwaway test publish, deprecated once `0.2.0` — the first real release — is out. ## Sitemap See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.