---
title: "Introduction"
description: "What nuxt-backend is, what it provides, and how it maps to the official Convex + Better Auth integration."
canonical_url: "https://nuxt-backend.dev/docs/start"
---
# Introduction

> What nuxt-backend is, what it provides, and how it maps to the official Convex + Better Auth integration.

`nuxt-backend` integrates [Convex](https://convex.dev) with [Nuxt](https://nuxt.com) — one package that ships a **Nuxt module** and an all-in-one **backend Convex component** with [Better Auth](https://www.better-auth.com) built in.

It is a Vue/Nuxt port of the official Convex + Better Auth React/Next integration. It keeps the same core pieces — the Better Auth Convex plugin, Convex auth config, server helpers, auth-aware preloading, and client auth state — but preconfigures the route wiring and component setup so new Nuxt apps do less manual installation work.

The generic Convex ⇄ Nuxt integration underneath — live queries and mutations, SSR helpers, the auth plumbing, DevTools, the Convex-aware CSP — is [`nuxt-convex-module`](https://github.com/qruto/nuxt-convex-module), installed and configured for you as a module dependency. This package speaks in backend terms (`useAuthState`, not `useConvexAuth`; the `auth` middleware, not `convex-auth`) and documents the surface it registers; the core data composables and components it passes through (`useQuery`, `useMutation`, `<Authenticated>`, …) follow that package's own guarantees.

<note>

This site covers the full surface. For a one-command start, jump straight to [Installation](https://nuxt-backend.dev/docs/start/installation).

</note>

## Two layers in one package

The package ships two things that work together:

<card-group>
<card icon="i-simple-icons-nuxtdotjs" title="Nuxt module">

Registers plugins, auto-imported composables and components, server utilities, the same-origin auth proxy, import aliases, and auto-scaffolds the Convex root files. Installed with `modules: ['nuxt-backend']`.

</card>

<card icon="i-lucide-database" title="Convex backend component">

Defines the all-in-one `backend` Convex component — auth tables + a Convex adapter for Better Auth persistence, transactional email (provider component nested inside), the billing entitlement cache, gift purchases, the AI metering records (reserve → settle), and the webhook delivery log — plus HTTP auth endpoints served through Convex. Mounted in your `convex.config.ts`.

</card>
</card-group>

The intended integration shape:

- **Nuxt** owns the UI, route middleware, SSR handlers, and the same-origin auth proxy.
- **Convex** owns data, real-time subscriptions, Better Auth persistence, and auth identity.
- **nuxt-backend** keeps the auth route, auth config, and client/server helpers aligned.

## What the module provides

Adding `modules: ['nuxt-backend']` registers the following surface:

- **Configuration** — a `backend` config key (`url`, `siteUrl`, `authRoute`, `scaffold`, `pages`, `autoEnv`, `mcp`, `devtools`) plus public/private runtime config, all falling back to env vars, and the typed `appConfig.backend` content layer (plan catalog, labels, brand).
- **Default pages** — `/login`, `/pricing`, `/settings`, `/profile`, `/security`, `/accept-invitation` and `/oauth/consent` mount out of the box; each can move, and an app page at the same route replaces it. See [Default Pages](https://nuxt-backend.dev/docs/ui/pages).
- **App runtime (Vue)** — a client Convex plugin and an SSR auth-token prefetch plugin (injects `$convex`); auto-imported composables (`useQuery`, `useMutation`, `useAuth`, `useBilling`, `usePasskeys`, …); auto-registered components (`<AuthForm>`, `<PricingTable>`, `<WorkspaceSettings>`, `<ProfileSettings>`, `<SecuritySettings>`, `<Authenticated>`, …); and an opt-in `auth` route middleware.
- **Styling** — the neutral `ui.css` stylesheet, auto-added and themeable through `--bk-*` tokens (see [Restyle with tokens](https://nuxt-backend.dev/docs/ui/customize/theming)), layered so the app's own CSS always wins.
- **Server (Nitro)** — a same-origin Better Auth proxy at `authRoute/**`, plus server auto-imports (`fetchQuery`, `preloadQuery`, `backendAuth`, …).
- **Agent surface** — an OAuth-protected MCP endpoint at `/mcp` and its two `/.well-known` discovery documents, in dev and production. See [MCP server](https://nuxt-backend.dev/docs/agents/mcp).
- **Security headers** — `nuxt-security`, installed by the module from its own dependency tree, with a Content Security Policy the Convex integration extends with the deployment origins; `security: false` in `nuxt.config` still switches it off. See [Security](https://nuxt-backend.dev/docs/ship/production/security).
- **Project wiring & types** — `#backend` import aliases for both Vite and Nitro, first-run scaffolded backend files, and full type augmentation.
- **Backend bridge** — package entrypoints you import inside your backend functions (`nuxt-backend/auth`, `nuxt-backend/app`, `nuxt-backend/billing`, `nuxt-backend/email`, …).
- **Backend components** — the all-in-one `backend` component (auth, email, billing cache, gifts, AI metering records, the webhook delivery log) plus bundled upstream [Convex components](https://www.convex.dev/components) (billing provider, rate limiting, workflows, migrations, aggregates) and native full-text search, wired into Better Auth and configured by the required env vars.

<tip>

Everything the module mounts is progressively replaceable — the [customization ladder](https://nuxt-backend.dev/docs/ui/customize): CSS tokens → `app.config` content → component slots → route shadowing → your own page built on the same composables. All-in-one defaults, zero lock-in, no eject step.

</tip>

## Official integration parity

`nuxt-backend` ports the official Better Auth Convex React/Next integration to Vue/Nuxt, giving each moving part Nuxt defaults:

<table>
<thead>
  <tr>
    <th>
      Official React/Next piece
    </th>
    
    <th>
      Nuxt/Vue equivalent
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Manual Better Auth Convex component files
    </td>
    
    <td>
      The packaged <code>
        nuxt-backend/convex.config
      </code>
      
      , mounted by the scaffolded <code>
        backend/convex.config.ts
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auth.config.ts
      </code>
      
       using the Better Auth Convex provider
    </td>
    
    <td>
      <code>
        nuxt-backend/auth.config
      </code>
      
      , scaffolded as <code>
        backend/auth.config.ts
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auth.ts
      </code>
      
       with <code>
        authComponent
      </code>
      
      , <code>
        createAuth
      </code>
      
       and the auth queries
    </td>
    
    <td>
      Scaffolded <code>
        backend/auth.ts
      </code>
      
       using <code>
        setupAuth(...)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Better Auth client with <code>
        convexClient()
      </code>
    </td>
    
    <td>
      Auto-created Vue Better Auth client exposed through <code>
        useAuth()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ConvexBetterAuthProvider
      </code>
    </td>
    
    <td>
      Nuxt client plugin plus <code>
        useAuthState()
      </code>
      
       state
    </td>
  </tr>
  
  <tr>
    <td>
      Next route handler proxy
    </td>
    
    <td>
      Nuxt server proxy at <code>
        backend.authRoute
      </code>
      
       (default <code>
        /api/auth
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        convexBetterAuthNextJs()
      </code>
    </td>
    
    <td>
      <code>
        backendAuth(event)
      </code>
      
       for H3/Nitro handlers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usePreloadedAuthQuery()
      </code>
    </td>
    
    <td>
      <code>
        usePreloadedAuthQuery()
      </code>
      
       for Vue hydration
    </td>
  </tr>
</tbody>
</table>

The goal is API parity where it matters, with less setup: Nuxt owns route registration, app scaffolding, composable auto-imports, and the same-origin auth proxy.

## Next steps

<card-group>
<card icon="i-lucide-download" title="Installation" to="https://nuxt-backend.dev/docs/start/installation">

Install the package, add the module, set env vars, and scaffold the Convex files.

</card>

<card icon="i-lucide-settings-2" title="Configuration" to="https://nuxt-backend.dev/docs/reference/configuration">

Module options, runtime config, and the full environment-variable reference.

</card>

<card icon="i-lucide-shield-check" title="Authentication" to="https://nuxt-backend.dev/docs/auth/sign-in">

Sign in from Nuxt, read session state, and protect routes.

</card>

<card icon="i-lucide-network" title="Architecture" to="https://nuxt-backend.dev/docs/start/concepts/how-it-works">

How the client, server, and auth proxy fit together.

</card>
</card-group>


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.