Command line
The better-convex-nuxt commands for development, the Convex CLI, and authentication setup.
The module installs the better-convex-nuxt command. Run it with pnpm exec better-convex-nuxt, or from a package.json script.
better-convex-nuxt dev [nuxt dev options]
better-convex-nuxt convex <command> [options]
better-convex-nuxt auth init [--typed-client] [--yes] [--site-url <origin>]
better-convex-nuxt auth schema --config <schema-options.ts> [options]
better-convex-nuxt --versionbetter-convex is a different project. Do not run npx better-convex: it downloads that package instead of this command.dev
dev runs convex dev and nuxt dev together, with [convex] and [nuxt] in front of each line. Ctrl-C stops both, and when one of them stops, dev stops the other.
{
"scripts": {
"dev": "better-convex-nuxt dev"
}
}- Without a deployment in
.env.local, Convex starts a local backend that needs no account (convex dev --anonymous). The first run downloads the backend and writes the deployment to.env.local. - With a deployment in
.env.local,devuses it. It must be a development, local, or anonymous deployment. - Nuxt starts when
.env.localhas the deployment URL. It getsCONVEX_URL,CONVEX_SITE_URLand your own values from.env.local(such asSITE_URL) on top of its.env, but not the deployment selector or keys. - Options after
devgo tonuxt dev, for examplebetter-convex-nuxt dev --port 3001.
A local backend has its dashboard on your machine. Open it with:
pnpm exec better-convex-nuxt convex dashboardauth init
auth init sets up authentication for a development deployment. It writes the auth files, generates the auth schema, and sets the development secrets and the first signing key. See add authentication for each step.
| Option | Effect |
|---|---|
--typed-client | Also write app/convex-auth.ts |
--yes, -y | Do every step without asking. Use it in scripts and CI. |
--site-url <origin> | The development site URL. Without it, the default is http://localhost:3000. |
auth init refuses a production deployment, also with --yes. It stops without changes when a file exists with other content. Running it again is safe.
Without --yes, auth init reads each answer from standard input, so you can also pipe answers:
printf 'y\ny\n\ny\n' | pnpm exec better-convex-nuxt auth initconvex
convex runs the Convex CLI that is installed in the project. It reads the deployment only from .env.local and removes every other Convex setting from the environment, so a command cannot reach another deployment by accident.
| Command | Deployment |
|---|---|
convex dev | A development, local, or anonymous deployment |
convex dev --anonymous | A new anonymous local deployment |
convex deploy | A production deploy key or a self-hosted backend |
convex codegen, env, run | The deployment in .env.local |
convex logs, convex data | The deployment in .env.local |
convex dashboard | The deployment in .env.local |
convex configure | Choose a deployment interactively |
convex deployment select <selector> | Choose a deployment by name |
Other options pass through to the Convex CLI. Options that choose a different deployment, such as --prod, --url, or --deployment, fail before the Convex CLI starts.
Code generation without a cloud deployment
convex codegen writes convex/_generated/ from the deployment in .env.local. It reads the components from that deployment, so it always needs one. Convex has no code generation without a deployment.
A local deployment is enough, and it needs no account and no network after the first run:
# Once: create an anonymous local deployment and write it to .env.local.
pnpm exec better-convex-nuxt convex dev --anonymous
# Then, after you add a module or an export:
pnpm exec better-convex-nuxt convex codegenWhen the local backend is not running, convex codegen starts it for the run and stops it after. The first convex dev --anonymous downloads the backend; later runs use the downloaded copy.
pnpm exec better-convex-nuxt convex logs --history 20
pnpm exec better-convex-nuxt convex data messages --limit 10auth schema
auth schema generates convex/betterAuth/schema.ts and schemaMetadata.ts from your Better Auth plugin list. auth init runs it for you. Run it again after you change convex/betterAuth/schemaPlugins.ts. See Better Auth plugins.