Skip to main content

Project structure

See where pages, Convex functions, auth files, and settings live after the quick start.

After Protect data, the app has these files. starters/tutorial is the same app, with tests.

my-convex-app/
├── app/
│   ├── app.vue                   # <NuxtPage /> and the layout styles
│   ├── convex-auth.ts            # browser auth client with the email-code plugin
│   └── pages/
│       ├── index.vue             # sign-in with an email code
│       └── todos.vue             # protected todo list
├── convex/
│   ├── _generated/               # generated by Convex; do not edit
│   ├── betterAuth/               # auth component; schema files are generated
│   ├── auth.config.ts            # lets Convex accept session tokens
│   ├── auth.ts                   # createBetterConvexAuth
│   ├── convex.config.ts          # registers the betterAuth component
│   ├── http.ts                   # /api/auth/* routes
│   ├── schema.ts                 # your tables
│   └── todos.ts                  # your queries and mutations
├── .env.local                    # not committed; deployment, URLs, secrets
├── nuxt.config.ts
└── package.json                  # "dev": "better-convex-nuxt dev"

Keep local settings in .env.local only. The better-convex-nuxt commands read it, and better-convex-nuxt dev passes its values to Nuxt. Commit a .env.example with the same names and empty secrets, so the next developer knows what to set. Set production values in your hosting platform, not in a file.

Where code goes

  • app/: pages and components. They call the composables and show state. Hiding a button here does not protect data.
  • convex/: functions that validate arguments, check the user, and read or write data. Put every permission check here.
  • server/: Nuxt server routes. Add one only when you need a server-side secret, a webhook, or your own HTTP API. Pages do not need a server route to call Convex. See server routes.
  • shared/: optional. Put validation schemas and types that both app/ and convex/ use here.

Better Auth client plugins

app/convex-auth.ts registers Better Auth client plugins, such as emailOTPClient(), and types their methods on useConvexAuth().client. Without the file, the browser auth client works with the default methods only.

The module looks for this file in the Nuxt srcDir, which is app/ in Nuxt 4. To use another path, set convex.auth.client in nuxt.config.ts. See Better Auth plugins.

Where tests go

  • Convex tests for permission checks and data rules
  • Nuxt tests for pages and route behavior
  • Browser tests for the full sign-in flow

A browser test alone does not prove that Convex rejects other users. Test the permission check in Convex too.