@convex-dev/static-hosting 0.1.2-beta.0

package/src/component/lib.test.ts

@@ -0,0 +1,110 @@
+/// <reference types="vite/client" />
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { api } from "./_generated/api.js";
+import { initConvexTest } from "./setup.test.js";
+
+describe("component lib", () => {
+  beforeEach(async () => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("can record and retrieve assets", async () => {
+    const t = initConvexTest();
+
+    // First upload a file to storage (mock with a fake storageId)
+    const uploadUrl = await t.mutation(api.lib.generateUploadUrl, {});
+    expect(uploadUrl).toBeDefined();
+    expect(typeof uploadUrl).toBe("string");
+  });
+
+  test("can look up assets by path", async () => {
+    const t = initConvexTest();
+
+    // Look up a non-existent path
+    const asset = await t.query(api.lib.getByPath, { path: "/index.html" });
+    expect(asset).toBeNull();
+  });
+
+  test("can list assets", async () => {
+    const t = initConvexTest();
+
+    const assets = await t.query(api.lib.listAssets, {});
+    expect(assets).toHaveLength(0);
+  });
+
+  test("gc removes old assets", async () => {
+    const t = initConvexTest();
+
+    // GC with no assets should return empty arrays
+    const result = await t.mutation(api.lib.gcOldAssets, {
+      currentDeploymentId: "test-deployment",
+    });
+    expect(result.storageIds).toHaveLength(0);
+    expect(result.blobIds).toHaveLength(0);
+  });
+
+  test("recordAsset returns old IDs when replacing", async () => {
+    const t = initConvexTest();
+
+    // Record a new asset (no previous) - should return nulls
+    const first = await t.mutation(api.lib.recordAsset, {
+      path: "/test.js",
+      blobId: "blob-123",
+      contentType: "application/javascript; charset=utf-8",
+      deploymentId: "deploy-1",
+    });
+    expect(first.oldStorageId).toBeNull();
+    expect(first.oldBlobId).toBeNull();
+
+    // Replace with a new blobId - should return the old one
+    const second = await t.mutation(api.lib.recordAsset, {
+      path: "/test.js",
+      blobId: "blob-456",
+      contentType: "application/javascript; charset=utf-8",
+      deploymentId: "deploy-2",
+    });
+    expect(second.oldStorageId).toBeNull();
+    expect(second.oldBlobId).toBe("blob-123");
+  });
+
+  test("gc returns blobIds for CDN assets", async () => {
+    const t = initConvexTest();
+
+    // Record a CDN asset
+    await t.mutation(api.lib.recordAsset, {
+      path: "/assets/main.js",
+      blobId: "blob-abc",
+      contentType: "application/javascript; charset=utf-8",
+      deploymentId: "deploy-old",
+    });
+
+    // GC should return the blobId
+    const result = await t.mutation(api.lib.gcOldAssets, {
+      currentDeploymentId: "deploy-new",
+    });
+    expect(result.storageIds).toHaveLength(0);
+    expect(result.blobIds).toEqual(["blob-abc"]);
+  });
+
+  test("asset with blobId can be looked up by path", async () => {
+    const t = initConvexTest();
+
+    await t.mutation(api.lib.recordAsset, {
+      path: "/assets/style.css",
+      blobId: "blob-xyz",
+      contentType: "text/css; charset=utf-8",
+      deploymentId: "deploy-1",
+    });
+
+    const asset = await t.query(api.lib.getByPath, {
+      path: "/assets/style.css",
+    });
+    expect(asset).not.toBeNull();
+    expect(asset!.blobId).toBe("blob-xyz");
+    expect(asset!.storageId).toBeUndefined();
+  });
+});

package/src/component/lib.ts

@@ -0,0 +1,228 @@
+import { v } from "convex/values";
+import { mutation, query, internalMutation } from "./_generated/server.js";
+
+// Validator for static asset documents (including system fields)
+const staticAssetValidator = v.object({
+  _id: v.id("staticAssets"),
+  _creationTime: v.number(),
+  path: v.string(),
+  storageId: v.optional(v.id("_storage")),
+  blobId: v.optional(v.string()),
+  contentType: v.string(),
+  deploymentId: v.string(),
+});
+
+/**
+ * Look up an asset by its URL path.
+ */
+export const getByPath = query({
+  args: { path: v.string() },
+  returns: v.union(staticAssetValidator, v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("staticAssets")
+      .withIndex("by_path", (q) => q.eq("path", args.path))
+      .unique();
+  },
+});
+
+/**
+ * Generate a signed URL for uploading a file to Convex storage.
+ * Note: This is kept for backwards compatibility but the recommended approach
+ * is to use the app's storage directly via exposeUploadApi().
+ */
+export const generateUploadUrl = mutation({
+  args: {},
+  returns: v.string(),
+  handler: async (ctx) => {
+    return await ctx.storage.generateUploadUrl();
+  },
+});
+
+/**
+ * Record an asset in the database after uploading to storage.
+ * If an asset already exists at this path, returns the old storageId for cleanup.
+ * 
+ * Note: Storage files are stored in the app's storage, not the component's storage.
+ * The caller is responsible for deleting the returned storageId from app storage.
+ */
+export const recordAsset = mutation({
+  args: {
+    path: v.string(),
+    storageId: v.optional(v.id("_storage")),
+    blobId: v.optional(v.string()),
+    contentType: v.string(),
+    deploymentId: v.string(),
+  },
+  returns: v.object({
+    oldStorageId: v.union(v.id("_storage"), v.null()),
+    oldBlobId: v.union(v.string(), v.null()),
+  }),
+  handler: async (ctx, args) => {
+    // Check if asset already exists at this path
+    const existing = await ctx.db
+      .query("staticAssets")
+      .withIndex("by_path", (q) => q.eq("path", args.path))
+      .unique();
+
+    let oldStorageId = null;
+    let oldBlobId = null;
+    if (existing) {
+      oldStorageId = existing.storageId ?? null;
+      oldBlobId = existing.blobId ?? null;
+      // Delete old record
+      await ctx.db.delete(existing._id);
+    }
+
+    // Insert new asset
+    await ctx.db.insert("staticAssets", {
+      path: args.path,
+      ...(args.storageId ? { storageId: args.storageId } : {}),
+      ...(args.blobId ? { blobId: args.blobId } : {}),
+      contentType: args.contentType,
+      deploymentId: args.deploymentId,
+    });
+
+    // Return old IDs so caller can clean up
+    return { oldStorageId, oldBlobId };
+  },
+});
+
+/**
+ * Garbage collect assets from old deployments.
+ * Returns the storageIds that need to be deleted from app storage.
+ */
+export const gcOldAssets = mutation({
+  args: {
+    currentDeploymentId: v.string(),
+  },
+  returns: v.object({
+    storageIds: v.array(v.id("_storage")),
+    blobIds: v.array(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const oldAssets = await ctx.db.query("staticAssets").collect();
+    const storageIds: Array<string> = [];
+    const blobIds: Array<string> = [];
+
+    for (const asset of oldAssets) {
+      if (asset.deploymentId !== args.currentDeploymentId) {
+        if (asset.storageId) {
+          storageIds.push(asset.storageId as unknown as string);
+        }
+        if (asset.blobId) {
+          blobIds.push(asset.blobId);
+        }
+        // Delete database record
+        await ctx.db.delete(asset._id);
+      }
+    }
+
+    return {
+      storageIds: storageIds as unknown as Array<ReturnType<typeof v.id<"_storage">>["type"]>,
+      blobIds,
+    };
+  },
+});
+
+/**
+ * List all assets (useful for debugging).
+ */
+export const listAssets = query({
+  args: {
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(staticAssetValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("staticAssets")
+      .order("asc")
+      .take(args.limit ?? 100);
+  },
+});
+
+/**
+ * Delete all assets records (useful for cleanup).
+ * Returns storageIds that need to be deleted from app storage.
+ */
+export const deleteAllAssets = internalMutation({
+  args: {},
+  returns: v.object({
+    storageIds: v.array(v.id("_storage")),
+    blobIds: v.array(v.string()),
+  }),
+  handler: async (ctx) => {
+    const assets = await ctx.db.query("staticAssets").collect();
+    const storageIds: Array<string> = [];
+    const blobIds: Array<string> = [];
+
+    for (const asset of assets) {
+      if (asset.storageId) {
+        storageIds.push(asset.storageId as unknown as string);
+      }
+      if (asset.blobId) {
+        blobIds.push(asset.blobId);
+      }
+      await ctx.db.delete(asset._id);
+    }
+
+    return {
+      storageIds: storageIds as unknown as Array<ReturnType<typeof v.id<"_storage">>["type"]>,
+      blobIds,
+    };
+  },
+});
+
+// ============================================================================
+// Deployment Tracking - for live reload on deploy
+// ============================================================================
+
+const deploymentInfoValidator = v.object({
+  _id: v.id("deploymentInfo"),
+  _creationTime: v.number(),
+  currentDeploymentId: v.string(),
+  deployedAt: v.number(),
+});
+
+/**
+ * Get the current deployment info.
+ * Clients subscribe to this to detect when a new deployment happens.
+ */
+export const getCurrentDeployment = query({
+  args: {},
+  returns: v.union(deploymentInfoValidator, v.null()),
+  handler: async (ctx) => {
+    return await ctx.db.query("deploymentInfo").first();
+  },
+});
+
+/**
+ * Update the current deployment ID.
+ * Called after a successful deployment to notify all connected clients.
+ */
+export const setCurrentDeployment = mutation({
+  args: {
+    deploymentId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    // Get existing deployment info
+    const existing = await ctx.db.query("deploymentInfo").first();
+
+    if (existing) {
+      // Update existing record
+      await ctx.db.patch(existing._id, {
+        currentDeploymentId: args.deploymentId,
+        deployedAt: Date.now(),
+      });
+    } else {
+      // Create new record
+      await ctx.db.insert("deploymentInfo", {
+        currentDeploymentId: args.deploymentId,
+        deployedAt: Date.now(),
+      });
+    }
+
+    return null;
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,21 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  staticAssets: defineTable({
+    path: v.string(), // URL path, e.g., "/index.html", "/assets/main-abc123.js"
+    storageId: v.optional(v.id("_storage")), // Reference to Convex file storage (used for HTML + non-CDN assets)
+    blobId: v.optional(v.string()), // convex-fs blob ID (used for CDN-served assets)
+    contentType: v.string(), // MIME type, e.g., "text/html; charset=utf-8"
+    deploymentId: v.string(), // UUID for garbage collection
+  })
+    .index("by_path", ["path"])
+    .index("by_deploymentId", ["deploymentId"]),
+
+  // Singleton table to track the current deployment
+  // Clients subscribe to this to know when to reload
+  deploymentInfo: defineTable({
+    currentDeploymentId: v.string(),
+    deployedAt: v.number(), // timestamp
+  }),
+});

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import schema from "./schema.js";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/react/index.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { useQuery } from "convex/react";
+import { useState, useMemo, type CSSProperties, type JSX } from "react";
+import type { FunctionReference } from "convex/server";
+
+type DeploymentInfo = {
+  _id: string;
+  _creationTime: number;
+  currentDeploymentId: string;
+  deployedAt: number;
+} | null;
+
+/**
+ * Hook to detect when a new deployment is available.
+ * Shows a prompt to the user instead of auto-reloading.
+ *
+ * @param getCurrentDeployment - The query function reference from exposeDeploymentQuery
+ * @returns Object with update status and reload function
+ *
+ * @example
+ * ```tsx
+ * import { useDeploymentUpdates } from "@convex-dev/static-hosting/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function App() {
+ *   const { updateAvailable, reload } = useDeploymentUpdates(
+ *     api.staticHosting.getCurrentDeployment
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       {updateAvailable && (
+ *         <div className="update-banner">
+ *           A new version is available!
+ *           <button onClick={reload}>Reload</button>
+ *         </div>
+ *       )}
+ *       {/* rest of your app *\/}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useDeploymentUpdates(
+  getCurrentDeployment: FunctionReference<"query", "public", Record<string, never>, DeploymentInfo>,
+) {
+  const deployment = useQuery(getCurrentDeployment, {});
+  const [initialDeploymentId, setInitialDeploymentId] = useState<string | null>(null);
+  const [dismissedDeploymentId, setDismissedDeploymentId] = useState<string | null>(null);
+
+  // Capture the initial deployment ID on first load
+  // Using useState with functional update to avoid stale closure issues
+  if (deployment && initialDeploymentId === null) {
+    // This is safe - we're setting initial state based on first data load
+    // It only runs once when deployment first becomes available
+    setInitialDeploymentId(deployment.currentDeploymentId);
+  }
+
+  // Derive updateAvailable from current state
+  const updateAvailable = useMemo(() => {
+    if (!deployment || initialDeploymentId === null) {
+      return false;
+    }
+    // Show update if deployment changed from initial AND user hasn't dismissed this one
+    const hasNewDeployment = deployment.currentDeploymentId !== initialDeploymentId;
+    const isDismissed = deployment.currentDeploymentId === dismissedDeploymentId;
+    return hasNewDeployment && !isDismissed;
+  }, [deployment, initialDeploymentId, dismissedDeploymentId]);
+
+  const reload = () => {
+    window.location.reload();
+  };
+
+  const dismiss = () => {
+    if (deployment) {
+      setDismissedDeploymentId(deployment.currentDeploymentId);
+    }
+  };
+
+  return {
+    /** True when a new deployment is available */
+    updateAvailable,
+    /** Reload the page to get the new version */
+    reload,
+    /** Dismiss the update notification (until next deploy) */
+    dismiss,
+    /** The current deployment info (or null if not yet loaded) */
+    deployment,
+  };
+}
+
+/**
+ * A ready-to-use update banner component.
+ * Displays a notification when a new deployment is available.
+ *
+ * @example
+ * ```tsx
+ * import { UpdateBanner } from "@convex-dev/static-hosting/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function App() {
+ *   return (
+ *     <div>
+ *       <UpdateBanner
+ *         getCurrentDeployment={api.staticHosting.getCurrentDeployment}
+ *       />
+ *       {/* rest of your app *\/}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function UpdateBanner({
+  getCurrentDeployment,
+  message = "A new version is available!",
+  buttonText = "Reload",
+  dismissable = true,
+  className,
+  style,
+}: {
+  getCurrentDeployment: FunctionReference<"query", "public", Record<string, never>, DeploymentInfo>;
+  message?: string;
+  buttonText?: string;
+  dismissable?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}): JSX.Element | null {
+  const { updateAvailable, reload, dismiss } = useDeploymentUpdates(getCurrentDeployment);
+
+  if (!updateAvailable) return null;
+
+  const defaultStyle: CSSProperties = {
+    position: "fixed",
+    bottom: "1rem",
+    right: "1rem",
+    backgroundColor: "#1a1a2e",
+    color: "#fff",
+    padding: "1rem 1.5rem",
+    borderRadius: "8px",
+    boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)",
+    display: "flex",
+    alignItems: "center",
+    gap: "1rem",
+    zIndex: 9999,
+    fontFamily: "system-ui, -apple-system, sans-serif",
+    fontSize: "14px",
+    ...style,
+  };
+
+  const buttonStyle: CSSProperties = {
+    backgroundColor: "#4f46e5",
+    color: "#fff",
+    border: "none",
+    padding: "0.5rem 1rem",
+    borderRadius: "4px",
+    cursor: "pointer",
+    fontWeight: 500,
+  };
+
+  const dismissStyle: CSSProperties = {
+    background: "none",
+    border: "none",
+    color: "#888",
+    cursor: "pointer",
+    padding: "0.25rem",
+    fontSize: "18px",
+    lineHeight: 1,
+  };
+
+  return (
+    <div className={className} style={defaultStyle}>
+      <span>{message}</span>
+      <button onClick={reload} style={buttonStyle}>
+        {buttonText}
+      </button>
+      {dismissable && (
+        <button onClick={dismiss} style={dismissStyle} aria-label="Dismiss">
+          ×
+        </button>
+      )}
+    </div>
+  );
+}

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "staticHosting",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };