ai-forge-cli 0.3.4 → 0.4.0

package/dist/{add-feature-MU65GMUK.js → add-feature-SOACPDYP.js}

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  insertAtMarker
+} from "./chunk-I7QOMYL4.js";
 import {
   camelCase,
   kebabCase,
@@ -109,30 +112,25 @@ async function updateConvexSchema(cwd, featureName) {
   }
   let content = await readFile(schemaPath);
   const importLine = `import { ${camelName}Tables } from "./features/${featureName}/schema";`;
-  const exportDefault = "export default defineSchema({";
-  if (content.includes(importLine)) {
-    logger.warn("Schema import already exists - skipping");
+  const spreadLine = `  ...${camelName}Tables,`;
+  const importResult = insertAtMarker(content, "imports", importLine, "ts");
+  if (!importResult.success) {
+    logger.warn("Markers not found in schema.ts - please add imports manually");
+    logger.warn(`  Add: ${importLine}`);
     return;
   }
-  const exportPos = content.indexOf(exportDefault);
-  if (exportPos === -1) {
-    logger.warn("Could not find 'export default defineSchema({' in schema.ts - skipping");
+  if (importResult.alreadyPresent) {
+    logger.warn("Schema import already exists - skipping");
     return;
   }
-  content = content.slice(0, exportPos) + importLine + "\n\n" + content.slice(exportPos);
-  const spreadLine = `  ...${camelName}Tables,`;
-  const defineSchemaStart = content.indexOf(exportDefault);
-  const afterDefineSchema = content.slice(defineSchemaStart + exportDefault.length);
-  const closingIndex = content.lastIndexOf("});");
-  if (closingIndex === -1) {
-    logger.warn("Could not find closing '});' in schema.ts - skipping spread");
+  content = importResult.content;
+  const tableResult = insertAtMarker(content, "tables", spreadLine, "ts");
+  if (!tableResult.success) {
+    logger.warn("Table markers not found in schema.ts - please add table spread manually");
+    logger.warn(`  Add: ${spreadLine}`);
     return;
   }
-  if (content.includes(spreadLine)) {
-    logger.warn("Schema spread already exists - skipping");
-  } else {
-    content = content.slice(0, closingIndex) + spreadLine + "\n" + content.slice(closingIndex);
-  }
+  content = tableResult.content;
   await writeFile(schemaPath, content);
   logger.success("Updated convex/schema.ts");
 }

package/dist/add-integration-DZT6E4XW.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import {
+  insertAtMarker,
+  replaceAtMarker
+} from "./chunk-I7QOMYL4.js";
+import {
+  renderTemplate
+} from "./chunk-PIFX2L5H.js";
+import {
+  fileExists,
+  logger,
+  readFile,
+  writeFile
+} from "./chunk-HL4K5AHI.js";
+
+// src/commands/add-integration.ts
+import { defineCommand } from "citty";
+import { spawn } from "child_process";
+import { join } from "path";
+import pc from "picocolors";
+var INTEGRATIONS = ["auth", "storage"];
+function runCommand(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: "inherit", cwd });
+    proc.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Command failed with code ${code}`));
+    });
+    proc.on("error", reject);
+  });
+}
+var add_integration_default = defineCommand({
+  meta: {
+    name: "add:integration",
+    description: "Add an infrastructure integration (auth, storage)"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: `Integration to add: ${INTEGRATIONS.join(", ")}`,
+      required: true
+    }
+  },
+  async run({ args }) {
+    const name = args.name;
+    const cwd = process.cwd();
+    if (!INTEGRATIONS.includes(name)) {
+      logger.error(`Unknown integration: ${name}`);
+      logger.log(`  Available: ${INTEGRATIONS.join(", ")}`);
+      process.exit(1);
+    }
+    logger.blank();
+    if (name === "auth") {
+      await setupAuth(cwd);
+    } else if (name === "storage") {
+      await setupStorage(cwd);
+    }
+  }
+});
+async function setupAuth(cwd) {
+  const authPath = join(cwd, "convex/auth.ts");
+  if (await fileExists(authPath)) {
+    logger.error("Auth already configured (convex/auth.ts exists)");
+    process.exit(1);
+  }
+  logger.log(`  ${pc.bold("Setting up Convex Auth...")}`);
+  logger.blank();
+  const step1 = logger.step("Installing dependencies...");
+  try {
+    await runCommand("pnpm", ["add", "@convex-dev/auth", "@auth/core"], cwd);
+    step1.succeed("Dependencies installed");
+  } catch {
+    step1.fail("Failed to install dependencies");
+    process.exit(1);
+  }
+  const step2 = logger.step("Creating auth files...");
+  try {
+    const files = [
+      { template: "integration/auth/convex/auth.ts.hbs", dest: "convex/auth.ts" },
+      { template: "integration/auth/convex/auth.config.ts.hbs", dest: "convex/auth.config.ts" },
+      { template: "integration/auth/convex/http.ts.hbs", dest: "convex/http.ts" },
+      { template: "integration/auth/src/lib/auth.ts.hbs", dest: "src/lib/auth.ts" }
+    ];
+    for (const file of files) {
+      const content = renderTemplate(file.template, {});
+      await writeFile(join(cwd, file.dest), content);
+    }
+    step2.succeed("Auth files created");
+  } catch (err) {
+    step2.fail("Failed to create auth files");
+    throw err;
+  }
+  const step3 = logger.step("Updating convex/schema.ts...");
+  try {
+    await updateSchemaForAuth(cwd);
+    step3.succeed("Schema updated");
+  } catch {
+    step3.fail("Failed to update schema");
+  }
+  const step4 = logger.step("Updating providers...");
+  try {
+    await updateProvidersForAuth(cwd);
+    step4.succeed("Providers updated");
+  } catch {
+    step4.fail("Failed to update providers");
+  }
+  const step5 = logger.step("Updating .env.example...");
+  try {
+    const envPath = join(cwd, ".env.example");
+    let env = await fileExists(envPath) ? await readFile(envPath) : "";
+    const authVars = `
+# Auth (get from GitHub/Google OAuth apps)
+AUTH_GITHUB_ID=
+AUTH_GITHUB_SECRET=
+AUTH_GOOGLE_ID=
+AUTH_GOOGLE_SECRET=
+`;
+    if (!env.includes("AUTH_GITHUB_ID")) {
+      await writeFile(envPath, env.trim() + "\n" + authVars);
+    }
+    step5.succeed(".env.example updated");
+  } catch {
+    step5.fail("Failed to update .env.example");
+  }
+  logger.blank();
+  logger.log(`  ${pc.green("\u2713")} ${pc.bold("Convex Auth configured!")}`);
+  logger.blank();
+  logger.log("  Next steps:");
+  logger.log("    1. Create OAuth apps on GitHub/Google");
+  logger.log("    2. Add secrets: npx convex env set AUTH_GITHUB_ID=xxx");
+  logger.log("    3. Generate JWT keys: npx @convex-dev/auth");
+  logger.log("    4. Run: npx convex dev");
+  logger.blank();
+}
+async function setupStorage(cwd) {
+  const storagePath = join(cwd, "convex/lib/storage.ts");
+  if (await fileExists(storagePath)) {
+    logger.error("Storage already configured (convex/lib/storage.ts exists)");
+    process.exit(1);
+  }
+  logger.log(`  ${pc.bold("Setting up Convex Storage...")}`);
+  logger.blank();
+  const step1 = logger.step("Creating storage files...");
+  try {
+    const files = [
+      { template: "integration/storage/convex/lib/storage.ts.hbs", dest: "convex/lib/storage.ts" },
+      { template: "integration/storage/src/lib/storage.ts.hbs", dest: "src/lib/storage.ts" }
+    ];
+    for (const file of files) {
+      const content = renderTemplate(file.template, {});
+      await writeFile(join(cwd, file.dest), content);
+    }
+    step1.succeed("Storage files created");
+  } catch (err) {
+    step1.fail("Failed to create storage files");
+    throw err;
+  }
+  logger.blank();
+  logger.log(`  ${pc.green("\u2713")} ${pc.bold("Convex Storage configured!")}`);
+  logger.blank();
+  logger.log("  Next steps:");
+  logger.log("    1. Use generateUploadUrl() in your mutations");
+  logger.log("    2. Use useUpload() hook in your components");
+  logger.blank();
+}
+async function updateSchemaForAuth(cwd) {
+  const schemaPath = join(cwd, "convex/schema.ts");
+  if (!await fileExists(schemaPath)) {
+    logger.warn("convex/schema.ts not found - skipping");
+    return;
+  }
+  let content = await readFile(schemaPath);
+  const importLine = 'import { authTables } from "@convex-dev/auth/server";';
+  const spreadLine = "  ...authTables,";
+  const importResult = insertAtMarker(content, "imports", importLine, "ts");
+  if (!importResult.success) {
+    logger.warn("Markers not found in schema.ts - please add auth import manually");
+    return;
+  }
+  if (importResult.alreadyPresent) {
+    return;
+  }
+  content = importResult.content;
+  const tableResult = insertAtMarker(content, "tables", spreadLine, "ts");
+  if (!tableResult.success) {
+    logger.warn("Table markers not found in schema.ts - please add auth tables manually");
+    return;
+  }
+  content = tableResult.content;
+  await writeFile(schemaPath, content);
+}
+async function updateProvidersForAuth(cwd) {
+  const providersPath = join(cwd, "src/providers/index.tsx");
+  if (!await fileExists(providersPath)) {
+    logger.warn("src/providers/index.tsx not found - skipping");
+    return;
+  }
+  let content = await readFile(providersPath);
+  if (content.includes("ConvexAuthProvider")) {
+    return;
+  }
+  const importLine = 'import { ConvexAuthProvider } from "@convex-dev/auth/react";';
+  const importResult = insertAtMarker(content, "imports", importLine, "ts");
+  if (!importResult.success) {
+    logger.warn("Import markers not found in providers - please add auth import manually");
+    return;
+  }
+  content = importResult.content;
+  const openResult = replaceAtMarker(
+    content,
+    "providers-open",
+    "    <ConvexAuthProvider client={convex}>",
+    "jsx"
+  );
+  if (!openResult.success) {
+    logger.warn("Provider markers not found - please update providers manually");
+    return;
+  }
+  content = openResult.content;
+  const closeResult = replaceAtMarker(
+    content,
+    "providers-close",
+    "    </ConvexAuthProvider>",
+    "jsx"
+  );
+  if (!closeResult.success) {
+    logger.warn("Provider close markers not found - please update providers manually");
+    return;
+  }
+  content = closeResult.content;
+  content = content.replace(
+    'import { ConvexProvider, ConvexReactClient } from "convex/react";',
+    'import { ConvexReactClient } from "convex/react";'
+  );
+  await writeFile(providersPath, content);
+}
+export {
+  add_integration_default as default
+};

package/dist/chunk-I7QOMYL4.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+// src/utils/markers.ts
+function insertAtMarker(content, marker, insertion, commentStyle = "ts") {
+  const startMarker = commentStyle === "ts" ? `// [forge:${marker}]` : `{/* [forge:${marker}] */}`;
+  const endMarker = commentStyle === "ts" ? `// [/forge:${marker}]` : `{/* [/forge:${marker}] */}`;
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx === -1 || endIdx === -1) {
+    return { success: false, content };
+  }
+  const markerContent = content.slice(startIdx, endIdx);
+  if (markerContent.includes(insertion.trim())) {
+    return { success: true, content, alreadyPresent: true };
+  }
+  const before = content.slice(0, endIdx);
+  const after = content.slice(endIdx);
+  return {
+    success: true,
+    content: `${before}${insertion}
+${after}`
+  };
+}
+function replaceAtMarker(content, marker, replacement, commentStyle = "ts") {
+  const startMarker = commentStyle === "ts" ? `// [forge:${marker}]` : `{/* [forge:${marker}] */}`;
+  const endMarker = commentStyle === "ts" ? `// [/forge:${marker}]` : `{/* [/forge:${marker}] */}`;
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx === -1 || endIdx === -1) {
+    return { success: false, content };
+  }
+  const before = content.slice(0, startIdx + startMarker.length);
+  const after = content.slice(endIdx);
+  return {
+    success: true,
+    content: `${before}
+${replacement}
+${after}`
+  };
+}
+
+export {
+  insertAtMarker,
+  replaceAtMarker
+};

package/dist/index.js

@@ -20,7 +20,8 @@ var main = defineCommand({
   },
   subCommands: {
     init: () => import("./init-OYJP5QCZ.js").then((m) => m.default),
-    "add:feature": () => import("./add-feature-MU65GMUK.js").then((m) => m.default),
+    "add:feature": () => import("./add-feature-SOACPDYP.js").then((m) => m.default),
+    "add:integration": () => import("./add-integration-DZT6E4XW.js").then((m) => m.default),
     check: () => import("./check-YMGJNKME.js").then((m) => m.default),
     version: () => import("./version-VO3LHLDO.js").then((m) => m.default)
   },

package/dist/templates/init/claude.md.hbs

@@ -22,12 +22,23 @@ The ONLY route you may create directly is `src/routes/index.tsx` (homepage).
 ## Commands
 
 ```bash
-pnpm dev              # Start dev server
-npx convex dev        # Start Convex backend
-pnpm lint             # Check with Biome
-forge check           # Validate architecture (run before finishing)
+pnpm dev                       # Start dev server
+npx convex dev                 # Start Convex backend
+pnpm lint                      # Check with Biome
+forge add:feature <name>       # Scaffold a new feature
+forge add:integration auth     # Add Convex Auth
+forge add:integration storage  # Add Convex file storage
+forge check                    # Validate architecture (run before finishing)
 ```
 
+## Integrations
+
+For infrastructure (not features), use `forge add:integration`:
+- `auth` - Convex Auth with GitHub/Google OAuth
+- `storage` - Convex file upload/download
+
+These create files in `convex/` and `src/lib/` - NOT in features.
+
 ## Architecture
 
 ```
@@ -35,8 +46,10 @@ src/routes/         → Thin route files (import from features, no logic)
 src/features/       → Feature code (components/, hooks.ts)
 src/components/ui/  → shadcn primitives only
 src/components/     → Truly shared components (Header, Footer, Logo)
-src/lib/            → Utilities
+src/lib/            → Utilities + integration hooks (auth.ts, storage.ts)
 convex/features/    → Backend (mirrors src/features/)
+convex/lib/         → Shared backend utilities (storage.ts)
+convex/auth.ts      → Auth configuration (from forge add:integration auth)
 ```
 
 ## Where Components Go

package/dist/templates/init/convex/schema.ts.hbs

@@ -1,7 +1,9 @@
 import { defineSchema } from "convex/server";
 
-// Feature table imports will be added here by forge add:feature
+// [forge:imports]
+// [/forge:imports]
 
 export default defineSchema({
-  // Feature tables will be spread here by forge add:feature
+  // [forge:tables]
+  // [/forge:tables]
 });

package/dist/templates/init/src/providers/index.tsx.hbs

@@ -1,3 +1,5 @@
+// [forge:imports]
+// [/forge:imports]
 import { ConvexProvider, ConvexReactClient } from "convex/react";
 import { useState } from "react";
 
@@ -6,5 +8,13 @@ export function Providers({ children }: { children: React.ReactNode }) {
     () => new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)
   );
 
-  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+  return (
+    {/* [forge:providers-open] */}
+    <ConvexProvider client={convex}>
+      {/* [/forge:providers-open] */}
+      {children}
+      {/* [forge:providers-close] */}
+    </ConvexProvider>
+    {/* [/forge:providers-close] */}
+  );
 }

package/dist/templates/integration/auth/convex/auth.config.ts.hbs

@@ -0,0 +1,8 @@
+export default {
+  providers: [
+    {
+      domain: process.env.CONVEX_SITE_URL,
+      applicationID: "convex",
+    },
+  ],
+};

package/dist/templates/integration/auth/convex/auth.ts.hbs

@@ -0,0 +1,7 @@
+import GitHub from "@auth/core/providers/github";
+import Google from "@auth/core/providers/google";
+import { convexAuth } from "@convex-dev/auth/server";
+
+export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
+  providers: [GitHub, Google],
+});

package/dist/templates/integration/auth/convex/http.ts.hbs

@@ -0,0 +1,8 @@
+import { httpRouter } from "convex/server";
+import { auth } from "./auth";
+
+const http = httpRouter();
+
+auth.addHttpRoutes(http);
+
+export default http;

package/dist/templates/integration/auth/src/lib/auth.ts.hbs

@@ -0,0 +1,14 @@
+import { useConvexAuth } from "convex/react";
+
+/**
+ * Hook to get authentication state
+ */
+export function useAuth() {
+  const { isAuthenticated, isLoading } = useConvexAuth();
+  return { isAuthenticated, isLoading };
+}
+
+/**
+ * Re-export auth components for convenience
+ */
+export { Authenticated, Unauthenticated, AuthLoading } from "convex/react";

package/dist/templates/integration/storage/convex/lib/storage.ts.hbs

@@ -0,0 +1,32 @@
+import { mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+/**
+ * Generate a URL for uploading a file
+ */
+export const generateUploadUrl = mutation({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.storage.generateUploadUrl();
+  },
+});
+
+/**
+ * Get a URL for accessing a stored file
+ */
+export const getUrl = query({
+  args: { storageId: v.id("_storage") },
+  handler: async (ctx, args) => {
+    return await ctx.storage.getUrl(args.storageId);
+  },
+});
+
+/**
+ * Delete a stored file
+ */
+export const deleteFile = mutation({
+  args: { storageId: v.id("_storage") },
+  handler: async (ctx, args) => {
+    return await ctx.storage.delete(args.storageId);
+  },
+});

package/dist/templates/integration/storage/src/lib/storage.ts.hbs

@@ -0,0 +1,42 @@
+import { useMutation, useQuery } from "convex/react";
+import { api } from "@convex/_generated/api";
+import type { Id } from "@convex/_generated/dataModel";
+
+/**
+ * Hook for uploading files to Convex storage
+ */
+export function useUpload() {
+  const generateUploadUrl = useMutation(api.lib.storage.generateUploadUrl);
+
+  const upload = async (file: File): Promise<Id<"_storage">> => {
+    const uploadUrl = await generateUploadUrl();
+
+    const response = await fetch(uploadUrl, {
+      method: "POST",
+      headers: { "Content-Type": file.type },
+      body: file,
+    });
+
+    const { storageId } = await response.json();
+    return storageId;
+  };
+
+  return { upload };
+}
+
+/**
+ * Hook for getting a file URL
+ */
+export function useFileUrl(storageId: Id<"_storage"> | null | undefined) {
+  return useQuery(
+    api.lib.storage.getUrl,
+    storageId ? { storageId } : "skip"
+  );
+}
+
+/**
+ * Hook for deleting a file
+ */
+export function useDeleteFile() {
+  return useMutation(api.lib.storage.deleteFile);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-forge-cli",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "TypeScript stack scaffolding & enforcement CLI for TanStack Start + Convex",
   "type": "module",
   "license": "MIT",

package/templates/init/claude.md.hbs

@@ -22,12 +22,23 @@ The ONLY route you may create directly is `src/routes/index.tsx` (homepage).
 ## Commands
 
 ```bash
-pnpm dev              # Start dev server
-npx convex dev        # Start Convex backend
-pnpm lint             # Check with Biome
-forge check           # Validate architecture (run before finishing)
+pnpm dev                       # Start dev server
+npx convex dev                 # Start Convex backend
+pnpm lint                      # Check with Biome
+forge add:feature <name>       # Scaffold a new feature
+forge add:integration auth     # Add Convex Auth
+forge add:integration storage  # Add Convex file storage
+forge check                    # Validate architecture (run before finishing)
 ```
 
+## Integrations
+
+For infrastructure (not features), use `forge add:integration`:
+- `auth` - Convex Auth with GitHub/Google OAuth
+- `storage` - Convex file upload/download
+
+These create files in `convex/` and `src/lib/` - NOT in features.
+
 ## Architecture
 
 ```
@@ -35,8 +46,10 @@ src/routes/         → Thin route files (import from features, no logic)
 src/features/       → Feature code (components/, hooks.ts)
 src/components/ui/  → shadcn primitives only
 src/components/     → Truly shared components (Header, Footer, Logo)
-src/lib/            → Utilities
+src/lib/            → Utilities + integration hooks (auth.ts, storage.ts)
 convex/features/    → Backend (mirrors src/features/)
+convex/lib/         → Shared backend utilities (storage.ts)
+convex/auth.ts      → Auth configuration (from forge add:integration auth)
 ```
 
 ## Where Components Go

package/templates/init/convex/schema.ts.hbs

@@ -1,7 +1,9 @@
 import { defineSchema } from "convex/server";
 
-// Feature table imports will be added here by forge add:feature
+// [forge:imports]
+// [/forge:imports]
 
 export default defineSchema({
-  // Feature tables will be spread here by forge add:feature
+  // [forge:tables]
+  // [/forge:tables]
 });

package/templates/init/src/providers/index.tsx.hbs

@@ -1,3 +1,5 @@
+// [forge:imports]
+// [/forge:imports]
 import { ConvexProvider, ConvexReactClient } from "convex/react";
 import { useState } from "react";
 
@@ -6,5 +8,13 @@ export function Providers({ children }: { children: React.ReactNode }) {
     () => new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)
   );
 
-  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+  return (
+    {/* [forge:providers-open] */}
+    <ConvexProvider client={convex}>
+      {/* [/forge:providers-open] */}
+      {children}
+      {/* [forge:providers-close] */}
+    </ConvexProvider>
+    {/* [/forge:providers-close] */}
+  );
 }

package/templates/integration/auth/convex/auth.config.ts.hbs

@@ -0,0 +1,8 @@
+export default {
+  providers: [
+    {
+      domain: process.env.CONVEX_SITE_URL,
+      applicationID: "convex",
+    },
+  ],
+};

package/templates/integration/auth/convex/auth.ts.hbs

@@ -0,0 +1,7 @@
+import GitHub from "@auth/core/providers/github";
+import Google from "@auth/core/providers/google";
+import { convexAuth } from "@convex-dev/auth/server";
+
+export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
+  providers: [GitHub, Google],
+});

package/templates/integration/auth/convex/http.ts.hbs

@@ -0,0 +1,8 @@
+import { httpRouter } from "convex/server";
+import { auth } from "./auth";
+
+const http = httpRouter();
+
+auth.addHttpRoutes(http);
+
+export default http;

package/templates/integration/auth/src/lib/auth.ts.hbs

@@ -0,0 +1,14 @@
+import { useConvexAuth } from "convex/react";
+
+/**
+ * Hook to get authentication state
+ */
+export function useAuth() {
+  const { isAuthenticated, isLoading } = useConvexAuth();
+  return { isAuthenticated, isLoading };
+}
+
+/**
+ * Re-export auth components for convenience
+ */
+export { Authenticated, Unauthenticated, AuthLoading } from "convex/react";

package/templates/integration/storage/convex/lib/storage.ts.hbs

@@ -0,0 +1,32 @@
+import { mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+/**
+ * Generate a URL for uploading a file
+ */
+export const generateUploadUrl = mutation({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.storage.generateUploadUrl();
+  },
+});
+
+/**
+ * Get a URL for accessing a stored file
+ */
+export const getUrl = query({
+  args: { storageId: v.id("_storage") },
+  handler: async (ctx, args) => {
+    return await ctx.storage.getUrl(args.storageId);
+  },
+});
+
+/**
+ * Delete a stored file
+ */
+export const deleteFile = mutation({
+  args: { storageId: v.id("_storage") },
+  handler: async (ctx, args) => {
+    return await ctx.storage.delete(args.storageId);
+  },
+});

package/templates/integration/storage/src/lib/storage.ts.hbs

@@ -0,0 +1,42 @@
+import { useMutation, useQuery } from "convex/react";
+import { api } from "@convex/_generated/api";
+import type { Id } from "@convex/_generated/dataModel";
+
+/**
+ * Hook for uploading files to Convex storage
+ */
+export function useUpload() {
+  const generateUploadUrl = useMutation(api.lib.storage.generateUploadUrl);
+
+  const upload = async (file: File): Promise<Id<"_storage">> => {
+    const uploadUrl = await generateUploadUrl();
+
+    const response = await fetch(uploadUrl, {
+      method: "POST",
+      headers: { "Content-Type": file.type },
+      body: file,
+    });
+
+    const { storageId } = await response.json();
+    return storageId;
+  };
+
+  return { upload };
+}
+
+/**
+ * Hook for getting a file URL
+ */
+export function useFileUrl(storageId: Id<"_storage"> | null | undefined) {
+  return useQuery(
+    api.lib.storage.getUrl,
+    storageId ? { storageId } : "skip"
+  );
+}
+
+/**
+ * Hook for deleting a file
+ */
+export function useDeleteFile() {
+  return useMutation(api.lib.storage.deleteFile);
+}