nuxt-convex 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,508 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/onmax/nuxt-convex/main/.github/og.webp" alt="Nuxt Convex" width="100%">
+</p>
+
+<h1 align="center">nuxt-convex</h1>
+
+<p align="center">Nuxt module for <a href="https://convex.dev">Convex</a> - reactive backend with real-time sync, file storage, and auto-imports.</p>
+
+<p align="center">
+  <a href="https://npmjs.com/package/nuxt-convex"><img src="https://img.shields.io/npm/v/nuxt-convex/latest.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm version"></a>
+  <a href="https://npm.chart.dev/nuxt-convex"><img src="https://img.shields.io/npm/dm/nuxt-convex.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm downloads"></a>
+  <a href="https://npmjs.com/package/nuxt-convex"><img src="https://img.shields.io/npm/l/nuxt-convex.svg?style=flat&colorA=020420&colorB=00DC82" alt="License"></a>
+  <a href="https://nuxt.com"><img src="https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js" alt="Nuxt"></a>
+</p>
+
+> **[Live Demo](https://nuxt-convex-playground.workers.dev)** · [Convex Docs](https://docs.convex.dev)
+
+## Features
+
+- **Real-time by default** - Queries auto-update when data changes
+- **Virtual modules** - Import from `#convex`, `#convex/api`, and `#convex/storage`
+- **Auto-imports** - Composables available without manual imports
+- **File storage** - Upload API with auto-scaffolded Convex functions
+- **DevTools** - Convex dashboard tab in Nuxt DevTools
+
+## Requirements
+
+- Nuxt 3.0.0 or higher
+- A Convex project (run `npx convex dev` to create one)
+
+## Setup
+
+Install the module and its peer dependencies:
+
+```bash
+pnpm add nuxt-convex convex @convex-vue/core
+```
+
+Add the module to your Nuxt configuration:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['nuxt-convex'],
+  convex: {
+    storage: true, // Enable file storage (optional)
+  },
+})
+```
+
+The module reads `CONVEX_URL` or `NUXT_PUBLIC_CONVEX_URL` environment variables automatically. Run `npx convex dev` to start the Convex development server.
+
+## Creating Your Backend
+
+Convex functions live in the `convex/` directory at your project root. See [Convex docs](https://docs.convex.dev/functions) for full reference.
+
+### Schema
+
+Define your database tables with [schemas](https://docs.convex.dev/database/schemas). Tables are created automatically when you push to Convex.
+
+```ts [convex/schema.ts]
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+
+export default defineSchema({
+  tasks: defineTable({
+    title: v.string(),
+    userId: v.optional(v.string()),
+    isCompleted: v.boolean(),
+    createdAt: v.number(),
+  }).index('by_user', ['userId']),
+})
+```
+
+The `v` object provides [validators](https://docs.convex.dev/database/schemas#validators) for all Convex types: `v.string()`, `v.number()`, `v.boolean()`, `v.id('tableName')`, `v.array()`, `v.object()`, `v.optional()`, `v.union()`, etc.
+
+### Queries
+
+[Queries](https://docs.convex.dev/functions/query-functions) read data from the database. They are reactive - the UI updates automatically when underlying data changes.
+
+```ts [convex/tasks.ts]
+import { v } from 'convex/values'
+import { query } from './_generated/server'
+
+export const list = query({
+  args: { userId: v.string() },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query('tasks')
+      .withIndex('by_user', q => q.eq('userId', userId))
+      .order('desc')
+      .collect()
+  },
+})
+
+export const get = query({
+  args: { id: v.id('tasks') },
+  handler: async (ctx, { id }) => {
+    return await ctx.db.get(id)
+  },
+})
+```
+
+### Mutations
+
+[Mutations](https://docs.convex.dev/functions/mutation-functions) write data to the database. They are transactional and run on the server.
+
+```ts [convex/tasks.ts]
+import { v } from 'convex/values'
+import { mutation } from './_generated/server'
+
+export const add = mutation({
+  args: { title: v.string(), userId: v.string() },
+  handler: async (ctx, { title, userId }) => {
+    return await ctx.db.insert('tasks', {
+      title,
+      userId,
+      isCompleted: false,
+      createdAt: Date.now(),
+    })
+  },
+})
+
+export const toggle = mutation({
+  args: { id: v.id('tasks') },
+  handler: async (ctx, { id }) => {
+    const task = await ctx.db.get(id)
+    if (task) {
+      await ctx.db.patch(id, { isCompleted: !task.isCompleted })
+    }
+  },
+})
+
+export const remove = mutation({
+  args: { id: v.id('tasks') },
+  handler: async (ctx, { id }) => {
+    await ctx.db.delete(id)
+  },
+})
+```
+
+### Actions
+
+[Actions](https://docs.convex.dev/functions/actions) run arbitrary code including external API calls, but cannot directly access the database. Use them for third-party integrations.
+
+```ts [convex/ai.ts]
+import { v } from 'convex/values'
+import { action } from './_generated/server'
+
+export const summarize = action({
+  args: { text: v.string() },
+  handler: async (ctx, { text }) => {
+    const response = await fetch('https://api.openai.com/v1/...', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
+      body: JSON.stringify({ prompt: text }),
+    })
+    return await response.json()
+  },
+})
+```
+
+Actions can call mutations/queries via `ctx.runMutation()` and `ctx.runQuery()`.
+
+## Usage
+
+Composables are auto-imported. They wrap [@convex-vue/core](https://github.com/niconiahi/convex-vue).
+
+### useConvexQuery
+
+Subscribe to a [query](https://docs.convex.dev/functions/query-functions). Returns reactive data that auto-updates when the database changes.
+
+```vue [app/pages/tasks.vue]
+<script setup lang="ts">
+import { api } from '#convex/api'
+
+const { data: tasks, isLoading, error } = useConvexQuery(api.tasks.list, { userId: 'user_123' })
+</script>
+
+<template>
+  <div v-if="isLoading">
+    Loading...
+  </div>
+  <div v-else-if="error">
+    Error: {{ error.message }}
+  </div>
+  <ul v-else>
+    <li v-for="task in tasks" :key="task._id">
+      {{ task.title }}
+    </li>
+  </ul>
+</template>
+```
+
+**Return values:**
+
+| Property    | Type                  | Description             |
+| ----------- | --------------------- | ----------------------- |
+| `data`      | `Ref<T \| undefined>` | Query result, reactive  |
+| `isLoading` | `Ref<boolean>`        | True while initial load |
+| `error`     | `Ref<Error \| null>`  | Error if query failed   |
+
+### useConvexMutation
+
+Call a [mutation](https://docs.convex.dev/functions/mutation-functions) to write data.
+
+```vue [app/components/AddTask.vue]
+<script setup lang="ts">
+import { api } from '#convex/api'
+
+const { mutate: addTask, isLoading, error } = useConvexMutation(api.tasks.add)
+
+const title = ref('')
+
+async function handleSubmit() {
+  await addTask({ title: title.value, userId: 'user_123' })
+  title.value = ''
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="title" :disabled="isLoading" placeholder="New task...">
+    <button :disabled="isLoading">
+      Add
+    </button>
+    <p v-if="error">
+      {{ error.message }}
+    </p>
+  </form>
+</template>
+```
+
+**Return values:**
+
+| Property    | Type                   | Description              |
+| ----------- | ---------------------- | ------------------------ |
+| `mutate`    | `(args) => Promise<T>` | Call the mutation        |
+| `isLoading` | `Ref<boolean>`         | True while running       |
+| `error`     | `Ref<Error \| null>`   | Error if mutation failed |
+
+### useConvexAction
+
+Call an [action](https://docs.convex.dev/functions/actions) for external API calls or long-running tasks.
+
+```vue [app/components/Summarize.vue]
+<script setup lang="ts">
+import { api } from '#convex/api'
+
+const { execute: summarize, isLoading, error } = useConvexAction(api.ai.summarize)
+
+const result = ref('')
+
+async function handleSummarize(text: string) {
+  result.value = await summarize({ text })
+}
+</script>
+```
+
+**Return values:**
+
+| Property    | Type                   | Description            |
+| ----------- | ---------------------- | ---------------------- |
+| `execute`   | `(args) => Promise<T>` | Call the action        |
+| `isLoading` | `Ref<boolean>`         | True while running     |
+| `error`     | `Ref<Error \| null>`   | Error if action failed |
+
+### useConvex
+
+Get the raw [ConvexClient](https://docs.convex.dev/api/classes/browser.ConvexClient) for advanced usage.
+
+```vue [app/components/Advanced.vue]
+<script setup lang="ts">
+import { api } from '#convex/api'
+
+const client = useConvex()
+
+// Direct client access for advanced patterns
+const result = await client.query(api.tasks.get, { id: 'abc123' })
+</script>
+```
+
+## File Storage
+
+Convex provides built-in [file storage](https://docs.convex.dev/file-storage). Enable it in your config to auto-scaffold the required functions.
+
+### Setup
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['nuxt-convex'],
+  convex: {
+    storage: true,
+  },
+})
+```
+
+This creates `convex/_hub/storage.ts` with `generateUploadUrl`, `getUrl`, and `remove` functions. Customize as needed.
+
+Add the `uploads` table to your schema:
+
+```ts [convex/schema.ts]
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+
+export default defineSchema({
+  uploads: defineTable({
+    storageId: v.id('_storage'),
+    name: v.string(),
+    type: v.string(),
+    url: v.optional(v.string()),
+    userId: v.string(),
+    createdAt: v.number(),
+  }).index('by_user', ['userId']),
+})
+```
+
+### useConvexStorage
+
+Low-level composable for storage operations. Auto-imported when storage is enabled.
+
+```vue [app/components/Storage.vue]
+<script setup lang="ts">
+import { api } from '#convex/api'
+
+const { generateUploadUrl, getUrl, remove } = useConvexStorage(api)
+
+// Get a reactive URL for a stored file
+const fileUrl = getUrl('storage_id_here')
+
+// Generate upload URL for direct upload
+const uploadUrl = await generateUploadUrl.mutate()
+
+// Delete a file
+await remove.mutate({ storageId: 'storage_id_here' })
+</script>
+```
+
+**Return values:**
+
+| Property            | Type                                         | Description           |
+| ------------------- | -------------------------------------------- | --------------------- |
+| `generateUploadUrl` | `{ mutate: () => Promise<string> }`          | Get URL for uploading |
+| `getUrl`            | `(storageId: string) => Ref<string \| null>` | Reactive file URL     |
+| `remove`            | `{ mutate: (args) => Promise<void> }`        | Delete a file         |
+
+### useConvexUpload
+
+High-level composable for file uploads with progress tracking. Auto-imported.
+
+```vue [app/pages/upload.vue]
+<script setup lang="ts">
+import { api } from '#convex/api'
+
+const { generateUploadUrl } = useConvexStorage(api)
+const saveFile = useConvexMutation(api._hub.storage.saveFile)
+
+const { upload, isUploading, progress, error } = useConvexUpload({
+  generateUploadUrl,
+  onSuccess: async (storageId, file) => {
+    await saveFile.mutate({
+      storageId,
+      name: file.name,
+      type: file.type,
+      userId: 'user_123',
+    })
+  },
+  onError: err => console.error('Upload failed:', err),
+})
+
+async function handleFileChange(event: Event) {
+  const file = (event.target as HTMLInputElement).files?.[0]
+  if (file) {
+    const storageId = await upload(file)
+    console.log('Uploaded:', storageId)
+  }
+}
+</script>
+
+<template>
+  <div>
+    <input type="file" :disabled="isUploading" @change="handleFileChange">
+    <p v-if="isUploading">
+      Uploading... {{ progress }}%
+    </p>
+    <p v-if="error">
+      {{ error.message }}
+    </p>
+  </div>
+</template>
+```
+
+**Options:**
+
+| Option              | Type                                      | Description                       |
+| ------------------- | ----------------------------------------- | --------------------------------- |
+| `generateUploadUrl` | `{ mutate: () => Promise<string> }`       | Required. From `useConvexStorage` |
+| `onSuccess`         | `(storageId: string, file: File) => void` | Called after successful upload    |
+| `onError`           | `(error: Error) => void`                  | Called on upload error            |
+
+**Return values:**
+
+| Property      | Type                                      | Description                      |
+| ------------- | ----------------------------------------- | -------------------------------- |
+| `upload`      | `(file: File) => Promise<string \| null>` | Upload a file, returns storageId |
+| `isUploading` | `Ref<boolean>`                            | True while uploading             |
+| `progress`    | `Ref<number>`                             | Upload progress 0-100            |
+| `error`       | `Ref<Error \| null>`                      | Error if upload failed           |
+
+## Configuration
+
+| Option    | Type      | Default                  | Description                     |
+| --------- | --------- | ------------------------ | ------------------------------- |
+| `url`     | `string`  | `process.env.CONVEX_URL` | Convex deployment URL           |
+| `storage` | `boolean` | `false`                  | Enable file storage integration |
+
+**Environment variables:**
+
+| Variable                 | Description                                     |
+| ------------------------ | ----------------------------------------------- |
+| `CONVEX_URL`             | Convex deployment URL (set by `npx convex dev`) |
+| `NUXT_PUBLIC_CONVEX_URL` | Alternative, follows Nuxt convention            |
+
+## DevTools
+
+When running in development, the module adds a **Convex** tab to Nuxt DevTools with an embedded Convex dashboard. Access your data, run functions, and view logs directly from DevTools.
+
+## Better Auth Integration
+
+Use [nuxt-better-auth](https://nuxt-better-auth.onmax.me/) for authentication alongside Convex for your app data.
+
+### 1. Install dependencies
+
+```bash
+pnpm add @onmax/nuxt-better-auth
+```
+
+### 2. Configure nuxt-better-auth
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['nuxt-convex', '@onmax/nuxt-better-auth'],
+  convex: { storage: true },
+})
+```
+
+### 3. Create server auth config
+
+```ts [server/auth.config.ts]
+import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
+
+export default defineServerAuth(() => ({
+  emailAndPassword: { enabled: true },
+}))
+```
+
+See [nuxt-better-auth docs](https://nuxt-better-auth.onmax.me/) for database adapters, social providers, and plugins.
+
+### Using Convex as Auth Database (Advanced)
+
+To store auth data directly in Convex instead of a SQL database:
+
+```bash
+pnpm add @convex-dev/better-auth better-auth --save-exact
+```
+
+```ts [convex/convex.config.ts]
+import betterAuth from '@convex-dev/better-auth/convex.config'
+import { defineApp } from 'convex/server'
+
+const app = defineApp()
+app.use(betterAuth)
+export default app
+```
+
+```ts [server/auth.config.ts]
+import { components } from '#convex/api'
+import { createClient } from '@convex-dev/better-auth'
+import { convex } from '@convex-dev/better-auth/server/plugins'
+import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
+
+const authComponent = createClient(components.betterAuth)
+
+export default defineServerAuth(() => ({
+  database: authComponent.adapter(),
+  plugins: [convex()],
+  emailAndPassword: { enabled: true },
+}))
+```
+
+This stores users, sessions, and accounts in Convex. See [@convex-dev/better-auth](https://github.com/get-convex/convex-better-auth) for details.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev:prepare
+pnpm dev
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+## License
+
+MIT

package/dist/module.d.mts

@@ -0,0 +1,17 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ConvexConfig {
+    /** Convex deployment URL. Auto-detected from CONVEX_URL or NUXT_PUBLIC_CONVEX_URL env vars */
+    url?: string;
+    /** Enable file storage integration. When true, scaffolds convex/_hub/storage.ts */
+    storage?: boolean;
+}
+interface ResolvedConvexConfig {
+    url: string;
+    storage: boolean;
+}
+
+declare const _default: _nuxt_schema.NuxtModule<ConvexConfig, ConvexConfig, false>;
+
+export { _default as default };
+export type { ConvexConfig, ResolvedConvexConfig };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-convex",
+  "version": "0.0.1-alpha.0",
+  "configKey": "convex",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,181 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+import { defineNuxtModule, createResolver, addPlugin, addImports, addTemplate, addTypeTemplate } from '@nuxt/kit';
+import { consola } from 'consola';
+import { defu } from 'defu';
+import { join } from 'pathe';
+
+const version = "0.0.1-alpha.0";
+
+const log = consola.withTag("nuxt:convex");
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-convex",
+    version,
+    configKey: "convex",
+    compatibility: { nuxt: ">=3.0.0" }
+  },
+  defaults: {
+    storage: false
+  },
+  async onInstall(nuxt) {
+    const options = nuxt.options.convex;
+    if (options?.storage) {
+      await scaffoldStorageFunctions(nuxt);
+    }
+  },
+  async setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    const config = resolveConfig(options);
+    nuxt.options.runtimeConfig.public.convex = defu(
+      nuxt.options.runtimeConfig.public.convex,
+      { url: config.url }
+    );
+    addPlugin({ src: resolve("./runtime/plugin.client"), mode: "client" });
+    addImports({ name: "useConvexUpload", from: resolve("./runtime/composables/useConvexUpload") });
+    setupConvexApiAlias(nuxt);
+    setupConvexClient(nuxt);
+    if (config.storage) {
+      await setupConvexStorage(nuxt, resolve);
+    }
+    if (nuxt.options.dev) {
+      addConvexDevTools(nuxt, config);
+    }
+    nuxt.hook("ready", () => {
+      if (config.url) {
+        log.info(`Convex connected: ${config.url}`);
+      } else {
+        log.warn("Convex URL not configured. Set CONVEX_URL or NUXT_PUBLIC_CONVEX_URL");
+      }
+    });
+  }
+});
+function resolveConfig(options) {
+  const url = options.url || process.env.CONVEX_URL || process.env.NUXT_PUBLIC_CONVEX_URL || "";
+  return defu(options, { url, storage: false });
+}
+function setupConvexClient(nuxt, _resolve) {
+  const template = addTemplate({
+    filename: "convex/client.mjs",
+    getContents: () => `// Auto-generated by nuxt-convex
+import { inject } from 'vue'
+import { CONVEX_INJECTION_KEY } from '@convex-vue/core'
+export { useConvexQuery, useConvexMutation, useConvexAction } from '@convex-vue/core'
+
+// Get the Convex client - MUST be called during component setup
+export function useConvex() {
+  const client = inject(CONVEX_INJECTION_KEY)
+  if (!client) throw new Error('[nuxt-convex] Convex client not found. Is the plugin installed?')
+  return client
+}
+`,
+    write: true
+  });
+  addTypeTemplate({
+    filename: "types/convex.d.ts",
+    getContents: () => `// Auto-generated by nuxt-convex
+import type { ConvexClient } from 'convex/browser'
+declare module '#convex' {
+  export { useConvexQuery, useConvexMutation, useConvexAction } from '@convex-vue/core'
+  export function useConvex(): ConvexClient
+}
+`
+  }, { nitro: true, nuxt: true });
+  nuxt.options.alias["#convex"] = template.dst;
+  addImports([
+    { name: "useConvexQuery", from: "#convex" },
+    { name: "useConvexMutation", from: "#convex" },
+    { name: "useConvexAction", from: "#convex" },
+    { name: "useConvex", from: "#convex" }
+  ]);
+}
+function setupConvexApiAlias(nuxt) {
+  const generatedDir = join(nuxt.options.rootDir, "convex/_generated");
+  if (!existsSync(generatedDir)) {
+    log.warn("convex/_generated not found. Run `npx convex dev` to generate types.");
+  }
+  nuxt.options.alias["#convex/api"] = join(generatedDir, "api");
+  addTypeTemplate({
+    filename: "types/convex-api.d.ts",
+    getContents: () => `// Auto-generated by nuxt-convex
+declare module '#convex/api' {
+  export * from '../../convex/_generated/api'
+}
+`
+  }, { nitro: true, nuxt: true });
+}
+async function setupConvexStorage(nuxt, resolve) {
+  const template = addTemplate({
+    filename: "convex/storage.mjs",
+    getContents: () => `// Auto-generated by nuxt-convex
+export { useConvexStorage } from '${resolve("./runtime/composables/useConvexStorage")}'
+`,
+    write: true
+  });
+  addTypeTemplate({
+    filename: "types/convex-storage.d.ts",
+    getContents: () => `// Auto-generated by nuxt-convex
+declare module '#convex/storage' {
+  import type { Ref } from 'vue'
+
+  export interface ConvexStorageReturn {
+    generateUploadUrl: () => Promise<string>
+    getUrl: (storageId: string) => Ref<string | null>
+    remove: (storageId: string) => Promise<void>
+  }
+
+  export function useConvexStorage(): ConvexStorageReturn
+}
+`
+  }, { nitro: true, nuxt: true });
+  nuxt.options.alias["#convex/storage"] = template.dst;
+  addImports({ name: "useConvexStorage", from: "#convex/storage" });
+  await scaffoldStorageFunctions(nuxt);
+}
+async function scaffoldStorageFunctions(nuxt) {
+  const storageDir = join(nuxt.options.rootDir, "convex", "_hub");
+  const storagePath = join(storageDir, "storage.ts");
+  if (existsSync(storagePath))
+    return;
+  await mkdir(storageDir, { recursive: true });
+  await writeFile(storagePath, `// Auto-generated by nuxt-convex - feel free to customize
+import { mutation, query } from '../_generated/server'
+import { v } from 'convex/values'
+
+export const generateUploadUrl = mutation(async (ctx) => {
+  return await ctx.storage.generateUploadUrl()
+})
+
+export const getUrl = query({
+  args: { storageId: v.id('_storage') },
+  handler: async (ctx, { storageId }) => {
+    return await ctx.storage.getUrl(storageId)
+  },
+})
+
+export const remove = mutation({
+  args: { storageId: v.id('_storage') },
+  handler: async (ctx, { storageId }) => {
+    await ctx.storage.delete(storageId)
+  },
+})
+`);
+  log.success("Created convex/_hub/storage.ts");
+}
+function addConvexDevTools(nuxt, config) {
+  nuxt.hook("devtools:customTabs", (tabs) => {
+    if (!config.url)
+      return;
+    const dashboardUrl = config.url.replace(".convex.cloud", ".convex.dev");
+    tabs.push({
+      category: "server",
+      name: "convex",
+      title: "Convex",
+      icon: "i-simple-icons-convex",
+      view: { type: "iframe", src: dashboardUrl }
+    });
+  });
+}
+
+export { module$1 as default };

package/dist/runtime/composables/useConvexStorage.d.ts

@@ -0,0 +1,28 @@
+import type { Ref } from '#imports';
+import type { FunctionReference } from 'convex/server';
+export interface ConvexStorageApi {
+    _hub?: {
+        storage?: {
+            generateUploadUrl: FunctionReference<'mutation'>;
+            getUrl: FunctionReference<'query'>;
+            remove: FunctionReference<'mutation'>;
+        };
+    };
+}
+export interface ConvexStorageReturn {
+    generateUploadUrl: {
+        mutate: () => Promise<string>;
+    };
+    getUrl: (storageId: string) => Ref<string | null>;
+    remove: {
+        mutate: (args: {
+            storageId: string;
+        }) => Promise<void>;
+    };
+}
+/**
+ * Composable for Convex file storage operations.
+ * MUST be called during component setup (not in onMounted/callbacks).
+ * @param api - The Convex API from `#convex/api`
+ */
+export declare function useConvexStorage(api: ConvexStorageApi): ConvexStorageReturn;

package/dist/runtime/composables/useConvexStorage.js

@@ -0,0 +1,34 @@
+import { inject, readonly, ref } from "#imports";
+import { CONVEX_INJECTION_KEY, useConvexQuery } from "@convex-vue/core";
+export function useConvexStorage(api) {
+  const storage = api?._hub?.storage;
+  if (!storage) {
+    console.warn("[nuxt-convex] Storage API not found. Ensure convex/_hub/storage.ts exists and `npx convex dev` is running.");
+  }
+  const client = inject(CONVEX_INJECTION_KEY);
+  if (!client) {
+    console.warn("[nuxt-convex] Convex client not found. Is the plugin installed?");
+  }
+  return {
+    generateUploadUrl: {
+      async mutate() {
+        if (!client || !storage?.generateUploadUrl)
+          throw new Error("[nuxt-convex] Storage API not configured");
+        return await client.mutation(storage.generateUploadUrl, {});
+      }
+    },
+    getUrl: (storageId) => {
+      if (!storage?.getUrl)
+        return readonly(ref(null));
+      const { data } = useConvexQuery(storage.getUrl, { storageId });
+      return readonly(data);
+    },
+    remove: {
+      async mutate(args) {
+        if (!client || !storage?.remove)
+          throw new Error("[nuxt-convex] Storage API not configured");
+        return await client.mutation(storage.remove, args);
+      }
+    }
+  };
+}

package/dist/runtime/composables/useConvexUpload.d.ts

@@ -0,0 +1,32 @@
+import type { DeepReadonly, Ref } from 'vue';
+export interface UseConvexUploadOptions {
+    /** Mutation to generate upload URL (from useConvexStorage or custom) */
+    generateUploadUrl: {
+        mutate: (args?: any) => Promise<string | undefined>;
+    };
+    /** Called on successful upload with storageId and file */
+    onSuccess?: (storageId: string, file: File) => void;
+    /** Called on upload error */
+    onError?: (error: Error) => void;
+}
+export interface UseConvexUploadReturn {
+    upload: (file: File) => Promise<string | null>;
+    isUploading: DeepReadonly<Ref<boolean>>;
+    progress: DeepReadonly<Ref<number>>;
+    error: DeepReadonly<Ref<Error | null>>;
+}
+/**
+ * Composable for uploading files to Convex storage.
+ *
+ * @example
+ * ```ts
+ * const { generateUploadUrl } = useConvexStorage()
+ * const { upload, isUploading, error } = useConvexUpload({
+ *   generateUploadUrl,
+ *   onSuccess: (id) => console.log('Uploaded:', id)
+ * })
+ *
+ * const handleFile = (file: File) => upload(file)
+ * ```
+ */
+export declare function useConvexUpload(options: UseConvexUploadOptions): UseConvexUploadReturn;

package/dist/runtime/composables/useConvexUpload.js

@@ -0,0 +1,45 @@
+import { readonly, ref } from "#imports";
+export function useConvexUpload(options) {
+  const _isUploading = ref(false);
+  const _progress = ref(0);
+  const _error = ref(null);
+  async function upload(file) {
+    if (import.meta.server) {
+      console.warn("[nuxt-convex] useConvexUpload can only be used on client-side");
+      return null;
+    }
+    _isUploading.value = true;
+    _progress.value = 0;
+    _error.value = null;
+    try {
+      const uploadUrl = await options.generateUploadUrl.mutate({});
+      if (!uploadUrl)
+        throw new Error("[nuxt-convex] Failed to generate upload URL");
+      const response = await fetch(uploadUrl, {
+        method: "POST",
+        headers: { "Content-Type": file.type },
+        body: file
+      });
+      if (!response.ok) {
+        throw new Error(`[nuxt-convex] Upload failed: ${response.statusText}`);
+      }
+      const { storageId } = await response.json();
+      _progress.value = 100;
+      options.onSuccess?.(storageId, file);
+      return storageId;
+    } catch (e) {
+      const error = e;
+      _error.value = error;
+      options.onError?.(error);
+      return null;
+    } finally {
+      _isUploading.value = false;
+    }
+  }
+  return {
+    upload,
+    isUploading: readonly(_isUploading),
+    progress: readonly(_progress),
+    error: readonly(_error)
+  };
+}

package/dist/runtime/plugin.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/plugin.client.js

@@ -0,0 +1,13 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
+import { createConvexVue } from "@convex-vue/core";
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig();
+  const convexUrl = config.public.convex?.url;
+  if (!convexUrl) {
+    console.warn("[nuxt-convex] No Convex URL configured. Set CONVEX_URL env var or run `npx convex dev`");
+    return;
+  }
+  const convex = createConvexVue({ convexUrl });
+  nuxtApp.vueApp.use(convex);
+  return { provide: { convex } };
+});

package/dist/types.d.mts

@@ -0,0 +1,9 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'
+
+export { type ConvexConfig, type ResolvedConvexConfig } from './module.mjs'

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "nuxt-convex",
+  "type": "module",
+  "version": "0.0.1-alpha.0",
+  "packageManager": "pnpm@10.15.1",
+  "description": "Nuxt module for Convex - reactive backend with real-time sync, file storage, and auto-imports",
+  "author": "onmax",
+  "license": "MIT",
+  "homepage": "https://github.com/onmax/nuxt-convex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onmax/nuxt-convex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/onmax/nuxt-convex/issues"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "convex",
+    "realtime",
+    "database",
+    "storage",
+    "vue"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare",
+    "playground:prepare": "nuxi prepare playground",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "nuxt-module-build build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "release": "bumpp && git push --follow-tags"
+  },
+  "peerDependencies": {
+    "@convex-vue/core": ">=0.0.4",
+    "convex": ">=1.0.0"
+  },
+  "dependencies": {
+    "@nuxt/kit": "catalog:prod",
+    "consola": "catalog:prod",
+    "defu": "catalog:prod",
+    "pathe": "catalog:prod"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "catalog:lint",
+    "@convex-vue/core": "catalog:convex",
+    "@nuxt/devtools": "catalog:nuxt",
+    "@nuxt/eslint-config": "catalog:lint",
+    "@nuxt/module-builder": "catalog:build",
+    "@nuxt/test-utils": "catalog:test",
+    "@types/node": "catalog:types",
+    "bumpp": "^10.3.2",
+    "convex": "catalog:convex",
+    "eslint": "catalog:lint",
+    "eslint-plugin-format": "catalog:lint",
+    "nuxt": "catalog:nuxt",
+    "typescript": "catalog:build",
+    "vitest": "catalog:test",
+    "vitest-package-exports": "catalog:test",
+    "vue": "catalog:nuxt",
+    "yaml": "catalog:"
+  }
+}