Refactor CLI and documentation for Convex Self Static Hosting. Updated README to replace 'module' terminology with 'component' for clarity. Simplified example code in main.tsx by removing the auto-detection helper. Enhanced Cloudflare setup script to verify user authentication and improved token retrieval process. Updated upload functionality to reflect component changes and ensure accurate logging during uploads.

Author: Seth Raphael

README.md

@@ -90,32 +90,19 @@ export const { generateUploadUrl, recordAsset, gcOldAssets, listAssets } =
 }
 ```
 
-The CLI will automatically find your `dist/` directory and upload to the `staticHosting` module.
+The CLI will automatically find your `dist/` directory and upload to the `staticHosting` component.
 
 **CLI Options:**
 ```bash
 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)
+  -c, --component <name>   Convex component name (default: staticHosting)
       --domain <name>   Domain for Cloudflare cache purge (auto-detects zone ID)
   -h, --help            Show help
 ```
 
-### 4. Update your app's entry point (optional)
-
-In your `main.tsx`, use the helper to auto-detect the Convex URL when deployed:
-
-```tsx
-import { ConvexProvider, ConvexReactClient } from "convex/react";
-import { getConvexUrlWithFallback } from "@get-convex/self-static-hosting";
-
-// Works both in development (uses VITE_CONVEX_URL) and production (auto-detects)
-const convexUrl = getConvexUrlWithFallback(import.meta.env.VITE_CONVEX_URL);
-const convex = new ConvexReactClient(convexUrl);
-```
-
 ## Deployment
 
 ```bash

example/src/main.tsx

@@ -1,15 +1,10 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { ConvexProvider, ConvexReactClient } from "convex/react";
-import { getConvexUrlWithFallback } from "@get-convex/self-static-hosting";
 import App from "./App.jsx";
 import "./index.css";
 
-// When running locally, use VITE_CONVEX_URL from .env.local
-// When deployed to Convex static hosting, derive the URL from the hostname
-const convexUrl = getConvexUrlWithFallback(import.meta.env.VITE_CONVEX_URL);
-
-const convex = new ConvexReactClient(convexUrl);
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>

src/cli/init.ts

@@ -92,38 +92,16 @@ export default http;
 }
 \`\`\`
 
-If using a path prefix, specify the module:
+If using a path prefix, specify the component:
 \`\`\`json
 {
   "scripts": {
-    "deploy:static": "npm run build && npx @get-convex/self-static-hosting upload --module staticHosting"
+    "deploy:static": "npm run build && npx @get-convex/self-static-hosting upload --component 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)
+### 5. src/App.tsx (optional: add live reload banner)
 
 \`\`\`typescript
 import { UpdateBanner } from "@get-convex/self-static-hosting/react";

src/cli/setup-cloudflare.ts

@@ -96,15 +96,43 @@ function getConvexSiteUrl(): string | null {
 }
 
 /**
- * Get API token from wrangler config
+ * Check if wrangler is logged in by running `wrangler whoami`
+ */
+function isWranglerLoggedIn(): boolean {
+  try {
+    const result = execSync("npx wrangler whoami", { stdio: "pipe", encoding: "utf-8" });
+    // If the command succeeds and doesn't contain "not authenticated", we're logged in
+    return !result.toLowerCase().includes("not authenticated");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get API token from wrangler config (checks multiple locations/formats)
  */
 function getWranglerToken(): string | null {
-  const configPath = join(homedir(), ".wrangler", "config", "default.toml");
-  if (existsSync(configPath)) {
-    const content = readFileSync(configPath, "utf-8");
-    const match = content.match(/oauth_token\s*=\s*"([^"]+)"/);
-    if (match) {
-      return match[1];
+  // Try the new config location first (wrangler 3.x+)
+  const configPaths = [
+    join(homedir(), ".wrangler", "config", "default.toml"),
+    join(homedir(), ".wrangler", "config.toml"),
+  ];
+  
+  const tokenPatterns = [
+    /oauth_token\s*=\s*"([^"]+)"/,
+    /access_token\s*=\s*"([^"]+)"/,
+    /token\s*=\s*"([^"]+)"/,
+  ];
+  
+  for (const configPath of configPaths) {
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, "utf-8");
+      for (const pattern of tokenPatterns) {
+        const match = content.match(pattern);
+        if (match) {
+          return match[1];
+        }
+      }
     }
   }
   return null;
@@ -281,8 +309,8 @@ async function main(): Promise<void> {
   log("");
   log("Step 2: Checking Cloudflare authentication...");
 
-  let token = getWranglerToken();
-  if (!token) {
+  let loggedIn = isWranglerLoggedIn();
+  if (!loggedIn) {
     info("Not logged in to Cloudflare.");
     const shouldLogin = await promptYesNo("Would you like to login now?");
     if (!shouldLogin) {
@@ -295,15 +323,35 @@ async function main(): Promise<void> {
     log("Opening browser for Cloudflare login...");
     spawnSync("npx", ["wrangler", "login"], { stdio: "inherit" });
 
-    token = getWranglerToken();
-    if (!token) {
+    // Verify login succeeded
+    loggedIn = isWranglerLoggedIn();
+    if (!loggedIn) {
       error("Login failed. Please try again.");
       rl.close();
       process.exit(1);
     }
   }
   success("Logged in to Cloudflare");
 
+  // Try to get OAuth token from wrangler config for API calls
+  let token = getWranglerToken();
+  if (!token) {
+    warn("Could not read wrangler OAuth token from config file.");
+    log("This may happen with newer versions of wrangler.");
+    log("");
+    log("Please create an API token manually:");
+    log("  1. Go to https://dash.cloudflare.com/profile/api-tokens");
+    log("  2. Click 'Create Token'");
+    log("  3. Use 'Edit zone DNS' template (or custom with Zone:Read, DNS:Edit, Cache Purge)");
+    log("");
+    token = await prompt("Paste your API token here: ");
+    if (!token) {
+      error("API token is required to continue.");
+      rl.close();
+      process.exit(1);
+    }
+  }
+
   // Step 3: Get Convex site URL
   log("");
   log("Step 3: Getting your Convex deployment URL...");

src/cli/upload.ts

@@ -7,7 +7,7 @@
  *
  * Options:
  *   --dist <path>       Path to dist directory (default: ./dist)
- *   --module <name>     Convex module with upload functions (default: staticHosting)
+ *   --component <name>  Convex component with upload functions (default: staticHosting)
  *   --domain <domain>   Domain for Cloudflare cache purge (auto-detects zone ID)
  *   --help              Show help
  */
@@ -47,15 +47,15 @@ function getMimeType(path: string): string {
 
 interface ParsedArgs {
   dist: string;
-  module: string;
+  component: string;
   domain: string | null;
   help: boolean;
 }
 
 function parseArgs(args: string[]): ParsedArgs {
   const result: ParsedArgs = {
     dist: "./dist",
-    module: "staticHosting",
+    component: "staticHosting",
     domain: null,
     help: false,
   };
@@ -66,8 +66,8 @@ function parseArgs(args: string[]): ParsedArgs {
       result.help = true;
     } else if (arg === "--dist" || arg === "-d") {
       result.dist = args[++i] || result.dist;
-    } else if (arg === "--module" || arg === "-m") {
-      result.module = args[++i] || result.module;
+    } else if (arg === "--component" || arg === "-c") {
+      result.component = args[++i] || result.component;
     } else if (arg === "--domain") {
       result.domain = args[++i] || null;
     }
@@ -83,10 +83,10 @@ Usage: npx @get-convex/self-static-hosting upload [options]
 Upload static files from a dist directory to Convex storage.
 
 Options:
-  -d, --dist <path>     Path to dist directory (default: ./dist)
-  -m, --module <name>   Convex module with upload functions (default: staticHosting)
-      --domain <name>   Domain for Cloudflare cache purge (e.g., example.com)
-  -h, --help            Show this help message
+  -d, --dist <path>        Path to dist directory (default: ./dist)
+  -c, --component <name>   Convex component with upload functions (default: staticHosting)
+      --domain <name>      Domain for Cloudflare cache purge (e.g., example.com)
+  -h, --help               Show this help message
 
 Cloudflare Cache Purging:
   The CLI will automatically purge Cloudflare cache if credentials are available.
@@ -277,7 +277,7 @@ async function main(): Promise<void> {
   }
 
   const distDir = resolve(args.dist);
-  const moduleName = args.module;
+  const componentName = args.component;
 
   if (!existsSync(distDir)) {
     console.error(`Error: dist directory not found: ${distDir}`);
@@ -292,14 +292,14 @@ async function main(): Promise<void> {
   console.log(
     `Uploading ${files.length} files with deployment ID: ${deploymentId}`,
   );
-  console.log(`Module: ${moduleName}`);
+  console.log(`Component: ${componentName}`);
   console.log("");
 
   for (const file of files) {
     const content = readFileSync(file.localPath);
 
     // Get upload URL via internal function
-    const uploadUrlOutput = convexRun(`${moduleName}:generateUploadUrl`);
+    const uploadUrlOutput = convexRun(`${componentName}:generateUploadUrl`);
     const uploadUrl = JSON.parse(uploadUrlOutput);
 
     // Upload to storage
@@ -312,7 +312,7 @@ async function main(): Promise<void> {
     const { storageId } = (await response.json()) as { storageId: string };
 
     // Record in database via internal function
-    convexRun(`${moduleName}:recordAsset`, {
+    convexRun(`${componentName}:recordAsset`, {
       path: file.path,
       storageId,
       contentType: file.contentType,
@@ -325,7 +325,7 @@ async function main(): Promise<void> {
   console.log("");
 
   // Garbage collect old files
-  const deletedOutput = convexRun(`${moduleName}:gcOldAssets`, {
+  const deletedOutput = convexRun(`${componentName}:gcOldAssets`, {
     currentDeploymentId: deploymentId,
   });
   const deleted = JSON.parse(deletedOutput);
@@ -364,7 +364,7 @@ async function main(): Promise<void> {
     console.log("☁️  Purging Cloudflare cache...");
     try {
       // Use Convex function (useful for CI/CD where you might want logging)
-      convexRun(`${moduleName}:purgeCloudflareCache`, {
+      convexRun(`${componentName}:purgeCloudflareCache`, {
         zoneId: cloudflareZoneId,
         apiToken: cloudflareApiToken,
         purgeAll: true,

src/client/index.ts

@@ -374,25 +374,6 @@ export function getConvexUrl(): string {
   );
 }
 
-/**
- * Get the Convex URL, with fallback to environment variable.
- * Safe to call in both browser and non-browser contexts when env var is set.
- *
- * @param envUrl - The environment variable value (e.g., import.meta.env.VITE_CONVEX_URL)
- *
- * @example
- * ```typescript
- * const convexUrl = getConvexUrlWithFallback(import.meta.env.VITE_CONVEX_URL);
- * ```
- */
-export function getConvexUrlWithFallback(envUrl?: string): string {
-  if (envUrl) {
-    return envUrl;
-  }
-
-  return getConvexUrl();
-}
-
 /**
  * Expose an action to purge Cloudflare cache after deployment.
  * This is optional - only needed if you're using Cloudflare as a CDN.