---
title: "Introduction"
description: "What nuxt-convex-module gives a Nuxt app, how it relates to Convex's own client, and what to read next."
canonical_url: "https://nuxt-convex-module.dev/getting-started/introduction"
---
# Introduction

> What nuxt-convex-module gives a Nuxt app, how it relates to Convex's own client, and what to read next.

<readme-hero>



</readme-hero>

`nuxt-convex-module` is the Convex client for Nuxt: live queries, mutations, actions, pagination, file storage and SSR, auto-imported and typed against your deployment. Install it, point it at a deployment, and your pages read and write Convex data reactively.

Underneath is a complete [Vue](https://vuejs.org) client with composables shaped the [VueUse](https://vueuse.org) way. It runs in a [plain-Vue app](https://nuxt-convex-module.dev/guide/plain-vue) too, with no Nuxt involved.

## What you get

- ⚡ **Live data** — [`useQuery`, `useQueries`](https://nuxt-convex-module.dev/guide/queries), [`useMutation`, `useAction`](https://nuxt-convex-module.dev/guide/mutations-and-actions) and cursor [`usePaginatedQuery`](https://nuxt-convex-module.dev/guide/pagination), over one `ConvexVueClient`.
- 🖥️ **SSR and preloading** — [`fetchQuery`, `preloadQuery` and `useAsyncQuery`](https://nuxt-convex-module.dev/guide/server-and-ssr) for hydration-safe server rendering.
- 📁 **File storage** — [`useUpload`, `useUploadQueue`, `useStorageUrl`](https://nuxt-convex-module.dev/guide/file-storage).
- 🔐 **Auth state** — provider-agnostic [`useConvexAuth` / `provideConvexAuth`](https://nuxt-convex-module.dev/guide/auth-state) and the `<Authenticated>` / `<Unauthenticated>` / `<AuthLoading>` / `<AuthRefreshing>` components.
- 🧩 **Opt-in integrations** — install [Better Auth, Clerk, Auth0 or Polar](https://nuxt-convex-module.dev/components) and they wire themselves up.
- 🛡️ **Security** — install [`nuxt-security`](https://nuxt-convex-module.dev/getting-started/security) and the CSP learns your deployment's origins; the auth proxy, SSR payloads and sign-in redirects ship hardened on their own.
- 🧰 **DevTools** — a Convex tab in [Nuxt DevTools](https://nuxt-convex-module.dev/guide/devtools): connection, live subscriptions, server logs, auth state.

### Only here

Some of that has no counterpart in Convex's React client — it exists because Nuxt makes it possible:

- 📁 **File storage composables** — `useUpload`, `useUploadQueue`, `useStorageUrl`: upload with progress, queue with bounded concurrency, resolve URLs reactively.
- 🖥️ **useAsyncQuery** — a Convex query with Nuxt's `useAsyncData` shape: real data in the server-rendered HTML, then live.
- 🔌 **The api object, provided app-wide** — namespace-reading composables and components work with zero arguments.
- 🛡️ **Security wiring** — the Convex-aware CSP, the hardened auth proxy, the `convex-auth` route middleware and `resolveAuthRedirect()`.
- 🧰 **The DevTools tab**, and `<AuthRefreshing>` for the token-refresh window.

<callout icon="i-lucide-blocks">

Core Convex is always on. Every opt-in package, and how it switches itself on, is in [Components](https://nuxt-convex-module.dev/components).

</callout>

## Where to start

1. [Install](https://nuxt-convex-module.dev/getting-started/installation) the module and run `dev` — one script starts Convex beside Nuxt.
2. [Configure](https://nuxt-convex-module.dev/getting-started/configuration) the deployment URL and the options you need.
3. Read [queries](https://nuxt-convex-module.dev/guide/queries) and [mutations](https://nuxt-convex-module.dev/guide/mutations-and-actions) — the rest of the guide builds on them; the [recipes](https://nuxt-convex-module.dev/recipes) show them combined.

## Coming from Convex React

The API is the one [Convex's React client](https://docs.convex.dev/client/react) documents. `useQuery`, `useMutation`, `usePaginatedQuery`, `preloadQuery` and `fetchQuery` keep their names, take the same function references and arguments, and resolve to the same values with the same loading and error semantics. A snippet from the Convex docs or a Stack article reads the same here; what changes is Vue's shape, never the Convex part.

`convex/react` and `convex/nextjs` are ported in full, hook for composable, and each integration is ported with its upstream public API. The port is kept diffable against the upstream sources, so it tracks releases file for file. The Convex release it matches:

<upstream-baseline source="convex">

Matches upstream convex@1.46.0 (convex/react + convex/nextjs).

</upstream-baseline>

### Reactivity, the VueUse way

- Inputs accept `MaybeRefOrGetter` and are read with `toValue`, so args stay reactive.
- Derived results are `ComputedRef`; owned subscription state is a writable `ShallowRef`.
- Where upstream returns an object (`useConvexAuth()`, `usePaginatedQuery()`), the fields are refs, so the documented destructuring stays reactive.
- Positional `useQuery` **throws** on error, like React's render-throw; the `_experimental` object form returns a `{ status }` union.

### Names and wiring

<table>
<thead>
  <tr>
    <th>
      Upstream
    </th>
    
    <th>
      Here
    </th>
    
    <th>
      Why
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        convex/react
      </code>
      
       — <code>
        ConvexReactClient
      </code>
    </td>
    
    <td>
      <code>
        ConvexVueClient
      </code>
    </td>
    
    <td>
      Same constructor, options and methods; <code>
        ReactMutation
      </code>
      
       / <code>
        ReactAction
      </code>
      
       are <code>
        VueMutation
      </code>
      
       / <code>
        VueAction
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        convex/react
      </code>
      
       — <code>
        <ConvexProvider client={…}>
      </code>
    </td>
    
    <td>
      the module's client plugin
    </td>
    
    <td>
      Nuxt builds and provides the client from your config; composables reach it with <code>
        useConvex()
      </code>
      
      . In <a href="https://nuxt-convex-module.dev/guide/plain-vue">
        plain Vue
      </a>
      
       you provide it yourself.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <ConvexProviderWithClerk>
      </code>
      
      , <code>
        <ConvexProviderWithAuth0>
      </code>
      
      , <code>
        <ConvexProviderWithAuth>
      </code>
    </td>
    
    <td>
      <a href="https://nuxt-convex-module.dev/components/clerk">
        <code>
          provideConvexAuthFromClerk()
        </code>
      </a>
      
      , <a href="https://nuxt-convex-module.dev/components/auth0">
        <code>
          provideConvexAuthFromAuth0()
        </code>
      </a>
      
      , <a href="https://nuxt-convex-module.dev/guide/auth-state">
        <code>
          provideConvexAuth()
        </code>
      </a>
    </td>
    
    <td>
      Auth is wired in <code>
        setup
      </code>
      
       rather than by a wrapper component. The Clerk and Auth0 components still ship as drop-ins; there is no <code>
        <ConvexProviderWithAuth>
      </code>
      
       component.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        convex/nextjs
      </code>
      
       — <code>
        NextjsOptions
      </code>
    </td>
    
    <td>
      <code>
        NuxtOptions
      </code>
    </td>
    
    <td>
      Only the name; <a href="https://nuxt-convex-module.dev/guide/server-and-ssr">
        <code>
          fetchQuery
        </code>
        
         / <code>
          fetchMutation
        </code>
        
         / <code>
          fetchAction
        </code>
        
         / <code>
          preloadQuery
        </code>
      </a>
      
       keep their signatures.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @convex-dev/better-auth
      </code>
      
       — <code>
        convexBetterAuthNextJs()
      </code>
    </td>
    
    <td>
      <a href="https://nuxt-convex-module.dev/components/better-auth">
        <code>
          convexAuth(event)
        </code>
      </a>
      
       (alias <code>
        convexBetterAuthNuxt
      </code>
      
      )
    </td>
    
    <td>
      Nitro has no ambient request context like <code>
        next/headers
      </code>
      
      , so the H3 <code>
        event
      </code>
      
       is passed explicitly.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @convex-dev/polar
      </code>
      
       — <code>
        <CheckoutLink polarApi>
      </code>
    </td>
    
    <td>
      <a href="https://nuxt-convex-module.dev/components/polar">
        <code>
          polarApi
        </code>
        
         is optional
      </a>
    </td>
    
    <td>
      It defaults to the auto-provided <code>
        api.billing
      </code>
      
       namespace.
    </td>
  </tr>
</tbody>
</table>

Everything else Vue-side is additive — [`useAsyncQuery`](https://nuxt-convex-module.dev/guide/server-and-ssr#useasyncquery-ssr-data-the-nuxt-way), the [file-storage composables](https://nuxt-convex-module.dev/guide/file-storage), `<AuthRefreshing>`, the [DevTools panel](https://nuxt-convex-module.dev/guide/devtools) — and displaces no upstream name. The full list of divergences and what is deliberately not ported is in [`PARITY.md`](https://github.com/qruto/nuxt-convex-module/blob/main/PARITY.md).

## Versioning

The module follows [semantic versioning](https://semver.org): everything you can write against — options, runtime config, aliases, auto-imports, subpath exports, peer floors — changes only in a major, and a deprecation stays for at least one minor first. The full promise is in [`STABILITY.md`](https://github.com/qruto/nuxt-convex-module/blob/main/STABILITY.md); every release is on the [changelog](https://nuxt-convex-module.dev/changelog).

### Experimental

<callout icon="i-lucide-flask-conical">

A symbol upstream marks experimental or unstable is experimental here: it may change in a minor release, always with a changelog entry. Each carries an `@experimental` tag in source and a callout like this one on its page.

</callout>

- [`useQuery_experimental`](https://nuxt-convex-module.dev/guide/queries#usequery_experimental) and `UseQueryResult`
- [`usePaginatedQuery_experimental`](https://nuxt-convex-module.dev/guide/pagination#usepaginatedquery_experimental), `UsePaginatedQueryOptions`, `UsePaginatedQueryObjectReturnType`, `resetPaginationId`
- [`<AuthBoundary>`](https://nuxt-convex-module.dev/components/better-auth#authboundary)
- [`useConvexConnectionState`](https://nuxt-convex-module.dev/guide/connection-state), the `ConnectionState` shape, `ConvexVueClient.connectionState()` and `.subscribeToConnectionState()`


## Sitemap

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