Update CLI for static file uploads with Cloudflare cache purging support. Modified package.json to change the upload script and added a post-install message. Enhanced README with quick start instructions for LLM integration and detailed cache purging options, including new command-line flags and environment variable setups.

sethconvex · sethconvex · commit 57f031e1d928 · 2026-01-14T19:51:36.000-08:00
diff --git a/README.md b/README.md
@@ -21,6 +21,18 @@ Install the component:
 npm install @get-convex/self-static-hosting
 ```
 
+### Quick Start with LLM
+
+Get comprehensive integration instructions to paste into your AI assistant:
+
+```bash
+npx @get-convex/self-static-hosting init
+```
+
+This outputs all the code you need to integrate the component.
+
+### Manual Setup
+
 Add to your `convex/convex.config.ts`:
 
 ```ts
@@ -86,6 +98,7 @@ npx @get-convex/self-static-hosting upload [options]
 Options:
   -d, --dist <path>     Path to dist directory (default: ./dist)
   -m, --module <name>   Convex module name (default: staticHosting)
+      --domain <name>   Domain for Cloudflare cache purge (auto-detects zone ID)
   -h, --help            Show help
 ```
 
@@ -190,29 +203,48 @@ Your app will be available at `https://yourdomain.com/app/`
    - `/app/assets/*` → Cache Level: Cache Everything, Edge TTL: 1 year
    - `/app/*` → Cache Level: Cache Everything, Edge TTL: 1 day
 
-### Optional: Cache Purging
+### Cache Purging
 
-To automatically purge Cloudflare cache on deploy:
+The CLI can automatically purge Cloudflare cache after deploying.
 
-1. **Expose the cache purge action** in your `convex/staticHosting.ts`:
-   ```ts
-   import { exposeCachePurgeAction } from "@get-convex/self-static-hosting";
-   
-   export const { purgeCloudflareCache } = exposeCachePurgeAction();
-   ```
+**Option 1: Use `--domain` flag (easiest)**
 
-2. **Get your Cloudflare credentials**:
-   - Zone ID: Found on your domain's overview page
-   - API Token: Create one at Account > API Tokens with "Cache Purge" permission
+```bash
+# First, login to Cloudflare via wrangler
+npx wrangler login
 
-3. **Set environment variables** before deploying:
-   ```bash
-   export CLOUDFLARE_ZONE_ID="your-zone-id"
-   export CLOUDFLARE_API_TOKEN="your-api-token"
-   npm run deploy:static
-   ```
+# Then deploy with your domain
+npx @get-convex/self-static-hosting upload --domain mysite.com
+```
 
-The deploy script will automatically purge the cache after uploading new files.
+The CLI will auto-detect your zone ID and purge the cache.
+
+**Option 2: Environment variables (for CI/CD)**
+
+```bash
+export CLOUDFLARE_ZONE_ID="your-zone-id"
+export CLOUDFLARE_API_TOKEN="your-api-token"
+npx @get-convex/self-static-hosting upload
+```
+
+To get these values:
+- Zone ID: Found on your domain's overview page in Cloudflare
+- API Token: Create at Account → API Tokens with "Cache Purge" permission
+
+**Option 3: Via Convex function (for advanced CI/CD)**
+
+Expose the cache purge action in your `convex/staticHosting.ts`:
+```ts
+import { exposeCachePurgeAction } from "@get-convex/self-static-hosting";
+
+export const { purgeCloudflareCache } = exposeCachePurgeAction();
+```
+
+Then call it from your CI/CD pipeline:
+```bash
+npx convex run staticHosting:purgeCloudflareCache \
+  '{"zoneId": "...", "apiToken": "...", "purgeAll": true}'
+```
 
 ## Live Reload on Deploy
 
diff --git a/package.json b/package.json
@@ -14,14 +14,15 @@
   ],
   "type": "module",
   "bin": {
-    "self-static-hosting": "./dist/cli/upload.js"
+    "self-static-hosting": "./dist/cli/index.js"
   },
   "scripts": {
+    "postinstall": "echo '\\n📦 @get-convex/self-static-hosting installed!\\n\\n   Run this command to get LLM integration instructions:\\n   npx @get-convex/self-static-hosting init\\n'",
     "dev": "run-p -r 'dev:*'",
     "dev:backend": "convex dev --typecheck-components",
     "dev:frontend": "cd example && vite --clearScreen false",
     "build:example": "cd example && vite build",
-    "upload:static": "node dist/cli/upload.js --dist ./example/dist --module example",
+    "upload:static": "node dist/cli/index.js upload --dist ./example/dist --module example",
     "deploy:static": "npm run build:example && npm run upload:static",
     "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build:codegen' --initial",
     "predev": "path-exists .env.local dist || (npm run build && convex dev --once)",
diff --git a/src/cli/index.ts b/src/cli/index.ts
@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for @get-convex/self-static-hosting
+ *
+ * Commands:
+ *   init     - Output integration instructions (LLM-friendly)
+ *   upload   - Upload static files to Convex
+ */
+
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+if (command === "init") {
+  // Run init command
+  const initPath = join(__dirname, "init.js");
+  await import(initPath);
+} else if (command === "upload" || !command || command === "--help" || command === "-h") {
+  // Run upload command (default)
+  const uploadPath = join(__dirname, "upload.js");
+  const uploadArgs = command === "upload" ? args : process.argv.slice(2);
+  
+  // Re-execute with upload script
+  const child = spawn(process.execPath, [uploadPath, ...uploadArgs], {
+    stdio: "inherit",
+  });
+  
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error("");
+  console.error("Available commands:");
+  console.error("  init     Output integration instructions for your LLM");
+  console.error("  upload   Upload static files to Convex storage");
+  console.error("");
+  console.error("Examples:");
+  console.error("  npx @get-convex/self-static-hosting init");
+  console.error("  npx @get-convex/self-static-hosting upload --dist ./dist");
+  process.exit(1);
+}
diff --git a/src/cli/init.ts b/src/cli/init.ts
@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Output integration instructions for LLMs.
+ *
+ * Usage:
+ *   npx @get-convex/self-static-hosting init
+ */
+
+const instructions = `
+# Convex Self Static Hosting - Integration Instructions
+
+You are integrating the @get-convex/self-static-hosting component into a Convex app.
+This component enables hosting static files (React/Vite apps) directly on Convex.
+
+## What This Component Does
+
+- Stores static files in Convex storage
+- Serves files via HTTP actions with proper MIME types
+- Supports SPA routing (fallback to index.html)
+- Smart caching: hashed assets cached forever, HTML revalidates
+- ETag support for efficient cache revalidation
+- Live reload notifications when new deployments happen
+- Optional Cloudflare CDN integration
+
+## Files to Create/Modify
+
+### 1. convex/convex.config.ts (create or modify)
+
+\`\`\`typescript
+import { defineApp } from "convex/server";
+import selfStaticHosting from "@get-convex/self-static-hosting/convex.config";
+
+const app = defineApp();
+app.use(selfStaticHosting);
+
+export default app;
+\`\`\`
+
+### 2. convex/staticHosting.ts (create)
+
+\`\`\`typescript
+import { components } from "./_generated/api";
+import {
+  exposeUploadApi,
+  exposeDeploymentQuery,
+  exposeCachePurgeAction,
+} from "@get-convex/self-static-hosting";
+
+// Internal functions for secure uploads (only callable via CLI)
+export const { generateUploadUrl, recordAsset, gcOldAssets, listAssets } =
+  exposeUploadApi(components.selfStaticHosting);
+
+// Public query for live reload notifications
+export const { getCurrentDeployment } =
+  exposeDeploymentQuery(components.selfStaticHosting);
+
+// Optional: Cloudflare cache purge (for CI/CD)
+export const { purgeCloudflareCache } = exposeCachePurgeAction();
+\`\`\`
+
+### 3. convex/http.ts (create or modify)
+
+\`\`\`typescript
+import { httpRouter } from "convex/server";
+import { registerStaticRoutes } from "@get-convex/self-static-hosting";
+import { components } from "./_generated/api";
+
+const http = httpRouter();
+
+// Option A: Serve at root (if no other HTTP routes)
+registerStaticRoutes(http, components.selfStaticHosting);
+
+// Option B: Serve at /app/ prefix (recommended if you have API routes)
+// registerStaticRoutes(http, components.selfStaticHosting, {
+//   pathPrefix: "/app",
+// });
+
+// Add other HTTP routes here if needed
+// http.route({ path: "/api/webhook", method: "POST", handler: ... });
+
+export default http;
+\`\`\`
+
+### 4. package.json scripts (add)
+
+\`\`\`json
+{
+  "scripts": {
+    "build": "vite build",
+    "deploy:static": "npm run build && npx @get-convex/self-static-hosting upload"
+  }
+}
+\`\`\`
+
+If using a path prefix, specify the module:
+\`\`\`json
+{
+  "scripts": {
+    "deploy:static": "npm run build && npx @get-convex/self-static-hosting upload --module staticHosting"
+  }
+}
+\`\`\`
+
+### 5. src/main.tsx (modify entry point)
+
+\`\`\`typescript
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { getConvexUrlWithFallback } from "@get-convex/self-static-hosting";
+import App from "./App";
+
+// Auto-detects Convex URL when deployed to *.convex.site
+const convexUrl = getConvexUrlWithFallback(import.meta.env.VITE_CONVEX_URL);
+const convex = new ConvexReactClient(convexUrl);
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <ConvexProvider client={convex}>
+      <App />
+    </ConvexProvider>
+  </React.StrictMode>
+);
+\`\`\`
+
+### 6. src/App.tsx (optional: add live reload banner)
+
+\`\`\`typescript
+import { UpdateBanner } from "@get-convex/self-static-hosting/react";
+import { api } from "../convex/_generated/api";
+
+function App() {
+  return (
+    <div>
+      {/* Shows banner when new deployment is available */}
+      <UpdateBanner
+        getCurrentDeployment={api.staticHosting.getCurrentDeployment}
+        message="New version available!"
+        buttonText="Refresh"
+      />
+      
+      {/* Rest of your app */}
+    </div>
+  );
+}
+\`\`\`
+
+Or use the hook for custom UI:
+\`\`\`typescript
+import { useDeploymentUpdates } from "@get-convex/self-static-hosting/react";
+import { api } from "../convex/_generated/api";
+
+function App() {
+  const { updateAvailable, reload, dismiss } = useDeploymentUpdates(
+    api.staticHosting.getCurrentDeployment
+  );
+  
+  // Custom update notification UI
+}
+\`\`\`
+
+## Deployment
+
+\`\`\`bash
+# Login to Convex (first time)
+npx convex login
+
+# Push Convex functions
+npx convex dev --once
+
+# Build and deploy static files
+npm run deploy:static
+
+# Your app is now live at:
+# https://your-deployment.convex.site
+# (or https://your-deployment.convex.site/app/ if using path prefix)
+\`\`\`
+
+## Optional: Cloudflare CDN
+
+For production with custom domain and edge caching:
+
+\`\`\`bash
+# Login to Cloudflare
+npx wrangler login
+
+# Deploy with automatic cache purge
+npx @get-convex/self-static-hosting upload --domain yourdomain.com
+\`\`\`
+
+Or for CI/CD, set environment variables:
+\`\`\`bash
+export CLOUDFLARE_ZONE_ID="your-zone-id"
+export CLOUDFLARE_API_TOKEN="your-api-token"
+npm run deploy:static
+\`\`\`
+
+## Important Notes
+
+1. The upload functions are INTERNAL - they can only be called via \`npx convex run\`, not from the public internet
+2. Static files are stored in the app's storage (not the component's) for proper isolation
+3. Hashed assets (e.g., main-abc123.js) get immutable caching; HTML files always revalidate
+4. The component supports SPA routing - routes without file extensions serve index.html
+`;
+
+console.log(instructions);
diff --git a/src/cli/upload.ts b/src/cli/upload.ts
