---
title: "Design your functions"
description: "Split Convex queries, mutations, and actions so they match the composables, and take the user from ctx.auth."
canonical_url: "https://nuxt-convex.onmax.me/convex-patterns/functions"
---
# Design your functions

> Split Convex queries, mutations, and actions so they match the composables, and take the user from ctx.auth.

The composables call normal public Convex functions. Keep the function boundary clear, and remember that public functions can be called by anyone with your deployment URL.

<note>

These examples scope data to the signed-in user, so they need [auth](https://nuxt-convex.onmax.me/integrations/better-auth). Without it, `list` returns `[]` and `add` throws `UNAUTHENTICATED`. To prototype first, drop `userId` and the identity checks, and add them back with auth.

</note>

## Use queries for reads

```ts [convex/tasks.ts]
import { query } from './_generated/server'

export const list = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity()
    if (!identity)
      return []
    return await ctx.db
      .query('tasks')
      .withIndex('by_user', q => q.eq('userId', identity.subject))
      .order('desc')
      .take(50)
  },
})
```

Queries back `useConvexQuery`, `useConvexQueries`, `useConvexPaginatedQuery`, and in Nuxt `serverConvexQuery`. They must be deterministic and can only read, which is what lets Convex rerun them and push updates.

A query that takes no arguments can be called without them: `useConvexQuery(api.tasks.list)`.

## Use mutations for writes

```ts [convex/tasks.ts]
import { ConvexError, v } from 'convex/values'
import { mutation } from './_generated/server'

export const add = mutation({
  args: { title: v.string() },
  handler: async (ctx, { title }) => {
    const identity = await ctx.auth.getUserIdentity()
    if (!identity)
      throw new ConvexError({ code: 'UNAUTHENTICATED' })
    if (!title.trim())
      throw new ConvexError({ code: 'EMPTY_TITLE' })

    return await ctx.db.insert('tasks', {
      title: title.trim(),
      userId: identity.subject,
      isCompleted: false,
      createdAt: Date.now(),
    })
  },
})
```

Mutations back `useConvexMutation` and support optimistic updates on the client. They run as transactions: all their writes land, or none do.

Take the user from `ctx.auth`, never from an argument: an argument is whatever the caller sends. Throw `ConvexError` for failures the UI should explain; the client can match them with [`isConvexError`](https://nuxt-convex.onmax.me/nuxt-module/error-handling).

## Use actions for orchestration or external work

```ts [convex/tasks.ts]
import { v } from 'convex/values'
import { api } from './_generated/api'
import { action } from './_generated/server'

export const importFromUrl = action({
  args: { url: v.string() },
  handler: async (ctx, { url }) => {
    const titles: string[] = await fetch(url).then(response => response.json())

    for (const title of titles)
      await ctx.runMutation(api.tasks.add, { title })

    return titles.length
  },
})
```

Actions back `useConvexAction`. They can call third-party APIs, but don't read or write the database directly: use `ctx.runQuery()` and `ctx.runMutation()`. The caller's identity is passed on to the functions they run.

## Next steps

- Read [Realtime and SSR](https://nuxt-convex.onmax.me/convex-patterns/realtime-and-ssr) to understand how query results move from server render to client subscription
- Read the [Nuxt track](https://nuxt-convex.onmax.me/nuxt) or the [Vue Guide](https://nuxt-convex.onmax.me/vue-guide) to consume these functions from the frontend


## Sitemap

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