convex-nuxt

Convex Nuxt Module

Convex integration for Nuxt 3. Uses convex-vue under the hood.

• ✨  Release Notes

Features

• Supports Convex realtime queries
• SSR and SSG support via suspense

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add convex-nuxt

Add the Convex URL to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['convex-nuxt'],
  convex: {
    url: 'https://your-convex-url.convex.dev', // Ideally from an env variable
  },
})

That's it! You can now use Convex Nuxt in your Nuxt app ✨

Authentication

Authentication providers can be connected to the module by creating a small plugin. The main purpose of this plugin is to pass a method that returns a token to Convex. This will allow Convex functions like queries and mutations to be aware of the user.

Clerk

Create a plugin in the plugins directory, e.g. plugins/convexClerk.ts and add the following code:

export default defineNuxtPlugin(() => {
  const convex = useConvexClient() // from convex-nuxt
  const auth = useAuth() // from @clerk/nuxt

  // Whenever Convex needs a token, it will call this function
  const getToken = async () => {
    return auth.getToken.value({
      template: 'convex',
      skipCache: false,
    })
  }

  convex.setAuth(getToken)
})

From this point on, you can implement the Clerk module as you would normally do. Also, the Convex functions will have access to the logged in user like below:

export const get = query({
  args: {},
  handler: async (ctx) => {
      const identity = await ctx.auth.getUserIdentity() // The logged in user from Clerk
  },
})

Contribution

Local development

# Install dependencies
bun install

# Generate type stubs
bun run dev:prepare

# Develop with the playground
bun run dev

# Build the playground
bun run dev:build

# Run ESLint
bun run lint

# Run Vitest
bun run test
bun run test:watch

# Release new version
bun run release