Update README and CLI to streamline deployment process. Changed installation instructions to use GitHub repository directly, emphasized the use of --build flag for production deployments, and clarified Cloudflare setup steps. Enhanced error messages in the CLI for better user guidance and added new command-line options for improved functionality.

Author: Seth Raphael

README.md

@@ -23,7 +23,7 @@ HTTP actions and file storage. No external hosting provider required!
 Install the component:
 
 ```bash
-npm install @get-convex/self-static-hosting
+npm install github:get-convex/self-static-hosting#main
 ```
 
 ### Quick Start with LLM

src/cli/index.ts

@@ -71,7 +71,7 @@ function printInitInstructions() {
 ## 1. Install the component
 
 \`\`\`bash
-npm install @get-convex/self-static-hosting
+npm install github:get-convex/self-static-hosting#main
 \`\`\`
 
 ## 2. Add to convex.config.ts

src/cli/init.ts

@@ -87,16 +87,21 @@ export default http;
 {
   "scripts": {
     "build": "vite build",
-    "deploy:static": "npm run build && npx @get-convex/self-static-hosting upload"
+    "deploy:static": "npx @get-convex/self-static-hosting upload --build --prod"
   }
 }
 \`\`\`
 
-If using a path prefix, specify the component:
+IMPORTANT: Use \`--build\` flag instead of running \`npm run build\` separately.
+The \`--build\` flag ensures \`VITE_CONVEX_URL\` is set correctly for the target
+environment (production or dev). Running build separately uses .env.local which
+has the dev URL.
+
+For custom domains with Cloudflare:
 \`\`\`json
 {
   "scripts": {
-    "deploy:static": "npm run build && npx @get-convex/self-static-hosting upload --component staticHosting"
+    "deploy:static": "npx @get-convex/self-static-hosting upload --build --prod --domain yourdomain.com"
   }
 }
 \`\`\`
@@ -143,42 +148,94 @@ function App() {
 # Login to Convex (first time)
 npx convex login
 
-# Push Convex functions
-npx convex dev --once
+# Deploy Convex backend to production FIRST
+npx convex deploy
 
-# Build and deploy static files
+# Deploy static files to production
 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 development/testing:
+\`\`\`bash
+# Push to dev environment
+npx convex dev --once
+
+# Deploy static files to dev (omit --prod)
+npx @get-convex/self-static-hosting upload --build
+\`\`\`
+
+## Optional: Cloudflare CDN with Custom Domain
+
+For production with a custom domain, edge caching, and DDoS protection.
 
-For production with custom domain and edge caching:
+### Quick Setup (Recommended)
+
+Run the interactive wizard:
 
 \`\`\`bash
-# Login to Cloudflare
-npx wrangler login
+npx @get-convex/self-static-hosting setup-cloudflare
+\`\`\`
 
-# Deploy with automatic cache purge
-npx @get-convex/self-static-hosting upload --domain yourdomain.com
+This wizard will:
+1. Login to Cloudflare (via wrangler)
+2. Let you select or add a domain
+3. Detect your production Convex deployment URL
+4. Configure DNS (CNAME pointing to your Convex site)
+5. Deploy a Cloudflare Worker to handle Host header rewriting
+6. Set SSL/TLS mode to "Full" (prevents redirect loops)
+7. Set up cache purge credentials
+8. Offer to deploy your Convex backend and static files
+
+After setup, deploy with:
+\`\`\`bash
+npm run deploy:static
 \`\`\`
 
-Or for CI/CD, set environment variables:
+The Cloudflare cache is automatically purged on each deploy.
+
+### Manual Cloudflare Setup
+
+If you prefer manual setup:
+
+1. Add your domain to Cloudflare
+2. Create a CNAME record pointing to your-deployment.convex.site
+3. Deploy a Cloudflare Worker to rewrite the Host header (required!)
+4. Set SSL/TLS mode to "Full" (not "Flexible")
+
+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
 \`\`\`
 
+## CLI Reference
+
+\`\`\`bash
+npx @get-convex/self-static-hosting upload [options]
+
+Options:
+  -d, --dist <path>        Path to dist directory (default: ./dist)
+  -c, --component <name>   Convex component name (default: staticHosting)
+      --prod               Deploy to production Convex deployment
+      --dev                Deploy to dev deployment (default)
+  -b, --build              Run 'npm run build' with correct VITE_CONVEX_URL
+      --domain <name>      Custom domain for URL output and cache purge
+  -h, --help               Show help
+\`\`\`
+
 ## 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
+5. Always use \`--build\` flag to ensure VITE_CONVEX_URL is set correctly for the target environment
+6. Deploy Convex backend (\`npx convex deploy\`) BEFORE deploying static files to production
 `;
 
 console.log(instructions);

src/cli/upload.ts

@@ -313,7 +313,9 @@ async function main(): Promise<void> {
         }
       } catch {
         console.error("Could not get production Convex URL.");
-        console.error("Make sure you have deployed to production: npx convex deploy");
+        console.error(
+          "Make sure you have deployed to production: npx convex deploy",
+        );
         process.exit(1);
       }
     } else {
@@ -355,7 +357,9 @@ async function main(): Promise<void> {
 
   if (!existsSync(distDir)) {
     console.error(`Error: dist directory not found: ${distDir}`);
-    console.error("Run your build command first (e.g., 'npm run build' or add --build flag)");
+    console.error(
+      "Run your build command first (e.g., 'npm run build' or add --build flag)",
+    );
     process.exit(1);
   }
 
@@ -503,7 +507,9 @@ async function main(): Promise<void> {
 
   if (!cachePurged && !args.domain) {
     console.log("");
-    console.log("💡 Tip: Add --domain yoursite.com to auto-purge Cloudflare cache");
+    console.log(
+      "💡 Tip: Add --domain yoursite.com to auto-purge Cloudflare cache",
+    );
     console.log("   (requires 'npx wrangler login' or CLOUDFLARE_API_TOKEN)");
   }
 }