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

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@convex-dev/static-hosting",
+  "description": "A static hosting component for Convex.",
+  "repository": "github:get-convex/static-hosting",
+  "homepage": "https://github.com/get-convex/static-hosting#readme",
+  "bugs": {
+    "url": "https://github.com/get-convex/static-hosting/issues"
+  },
+  "version": "0.1.2-beta.0",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component"
+  ],
+  "type": "module",
+  "bin": {
+    "static-hosting": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "postinstall": "echo '\\n📦 @convex-dev/static-hosting installed!\\n\\n   🚀 Quick Setup (Interactive):\\n   npx @convex-dev/static-hosting setup\\n\\n   🤖 For LLMs: See INTEGRATION.md for complete integration instructions\\n   📖 Manual Setup: npx @convex-dev/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/index.js upload --dist ./example/dist --component staticHosting",
+    "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)",
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "all": "run-p -r 'dev:*' 'test:watch'",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "preversion": "npm ci && npm run build:clean && run-p test lint typecheck",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "version": "vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./next": {
+      "types": "./dist/client/next.d.ts",
+      "default": "./dist/client/next.js"
+    },
+    "./nextAdapter": {
+      "types": "./dist/client/nextAdapter.d.ts",
+      "default": "./dist/client/nextAdapter.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "dependencies": {
+    "fetch-to-node": "^2.1.0"
+  },
+  "peerDependencies": {
+    "convex": "^1.29.3",
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.1.1",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "9.39.1",
+    "@types/node": "^24.10.4",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "chokidar-cli": "3.0.0",
+    "convex": "1.31.0",
+    "convex-test": "0.0.40",
+    "cpy-cli": "^6.0.0",
+    "eslint": "9.39.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^17.0.0",
+    "npm-run-all2": "8.0.4",
+    "path-exists-cli": "2.0.0",
+    "pkg-pr-new": "^0.0.60",
+    "prettier": "3.6.2",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.47.0",
+    "vite": "7.2.6",
+    "vitest": "4.0.17"
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js"
+}

package/src/cli/deploy.ts

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+/**
+ * One-shot deployment command that deploys both Convex backend and static files.
+ *
+ * Usage:
+ *   npx @convex-dev/static-hosting deploy [options]
+ *
+ * This command:
+ * 1. Builds the frontend with the correct VITE_CONVEX_URL
+ * 2. Deploys the Convex backend (npx convex deploy)
+ * 3. Deploys static files to Convex storage
+ *
+ * The goal is to minimize the inconsistency window between backend and frontend.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { execSync, spawnSync } from "child_process";
+
+interface ParsedArgs {
+  dist: string;
+  component: string;
+  help: boolean;
+  skipBuild: boolean;
+  skipConvex: boolean;
+  cdn: boolean;
+  dev: boolean;
+}
+
+function parseArgs(args: string[]): ParsedArgs {
+  const result: ParsedArgs = {
+    dist: "./dist",
+    component: "staticHosting",
+    help: false,
+    skipBuild: false,
+    skipConvex: false,
+    cdn: false,
+    dev: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+    } else if (arg === "--dist" || arg === "-d") {
+      result.dist = args[++i] || result.dist;
+    } else if (arg === "--component" || arg === "-c") {
+      result.component = args[++i] || result.component;
+    } else if (arg === "--skip-build") {
+      result.skipBuild = true;
+    } else if (arg === "--skip-convex") {
+      result.skipConvex = true;
+    } else if (arg === "--cdn") {
+      result.cdn = true;
+    } else if (arg === "--dev") {
+      result.dev = true;
+    }
+  }
+
+  return result;
+}
+
+function showHelp(): void {
+  console.log(`
+Usage: npx @convex-dev/static-hosting deploy [options]
+
+One-shot deployment: builds frontend, deploys Convex backend, then deploys static files.
+Minimizes the inconsistency window between backend and frontend updates.
+
+Options:
+  -d, --dist <path>           Path to dist directory (default: ./dist)
+  -c, --component <name>      Convex component name (default: staticHosting)
+      --skip-build            Skip the build step (use existing dist)
+      --skip-convex           Skip Convex backend deployment
+      --cdn                   Upload non-HTML assets to convex-fs CDN
+      --dev                   Deploy to dev environment (skip backend deploy, upload without --prod)
+  -h, --help                  Show this help message
+
+Deployment Flow (production, default):
+  1. Build frontend with production VITE_CONVEX_URL
+  2. Deploy Convex backend (npx convex deploy)
+  3. Deploy static files to Convex storage
+
+Deployment Flow (--dev):
+  1. Build frontend with dev VITE_CONVEX_URL (from .env.local)
+  2. Skip Convex backend deployment (use running 'npx convex dev')
+  3. Deploy static files to dev Convex storage
+
+Examples:
+  # Full production deployment
+  npx @convex-dev/static-hosting deploy
+
+  # Deploy to dev environment
+  npx @convex-dev/static-hosting deploy --dev
+
+  # Skip build (if already built)
+  npx @convex-dev/static-hosting deploy --skip-build
+
+  # Only deploy static files (skip Convex backend)
+  npx @convex-dev/static-hosting deploy --skip-convex
+`);
+}
+
+/**
+ * Get the production Convex URL
+ */
+function getConvexProdUrl(): string | null {
+  try {
+    const result = execSync("npx convex env get CONVEX_CLOUD_URL --prod", {
+      stdio: "pipe",
+      encoding: "utf-8",
+    });
+    return result.trim() || null;
+  } catch {
+    // Fall back to env files
+  }
+
+  // Try env files as fallback
+  const envFiles = [".env.production", ".env.production.local", ".env.local"];
+  for (const envFile of envFiles) {
+    if (existsSync(envFile)) {
+      const content = readFileSync(envFile, "utf-8");
+      const match = content.match(/(?:VITE_)?CONVEX_URL=(.+)/);
+      if (match) {
+        return match[1].trim();
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get the dev Convex URL (from running `npx convex dev`)
+ */
+function getConvexDevUrl(): string | null {
+  try {
+    const result = execSync("npx convex env get CONVEX_CLOUD_URL", {
+      stdio: "pipe",
+      encoding: "utf-8",
+    });
+    return result.trim() || null;
+  } catch {
+    // Fall back to env files
+  }
+
+  // Try .env.local (standard location for dev URL)
+  const envFiles = [".env.local", ".env.development.local", ".env.development"];
+  for (const envFile of envFiles) {
+    if (existsSync(envFile)) {
+      const content = readFileSync(envFile, "utf-8");
+      const match = content.match(/(?:VITE_)?CONVEX_URL=(.+)/);
+      if (match) {
+        return match[1].trim();
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Run the Convex storage upload flow
+ */
+async function uploadToConvexStorage(
+  distDir: string,
+  componentName: string,
+  useCdn: boolean,
+  prod: boolean,
+): Promise<boolean> {
+  console.log("");
+  console.log(useCdn
+    ? "📦 Uploading static files (HTML to Convex, assets to CDN)..."
+    : "📦 Uploading static files to Convex storage...");
+  console.log("");
+
+  const uploadArgs = [
+    "@convex-dev/static-hosting",
+    "upload",
+    "--dist",
+    distDir,
+    "--component",
+    componentName,
+  ];
+
+  if (prod) {
+    uploadArgs.push("--prod");
+  }
+
+  if (useCdn) {
+    uploadArgs.push("--cdn");
+  }
+
+  const result = spawnSync("npx", uploadArgs, { stdio: "inherit" });
+
+  return result.status === 0;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const isDev = args.dev;
+
+  // --dev implies --skip-convex (backend is managed by `npx convex dev`)
+  if (isDev) {
+    args.skipConvex = true;
+  }
+
+  console.log("");
+  console.log(isDev
+    ? "🚀 Convex + Static Files Deployment (dev)"
+    : "🚀 Convex + Static Files Deployment");
+  console.log("═══════════════════════════════════════════════════════════");
+
+  const startTime = Date.now();
+
+  // Step 1: Get Convex URL (needed for build)
+  console.log("");
+  console.log(isDev
+    ? "Step 1: Getting dev Convex URL..."
+    : "Step 1: Getting production Convex URL...");
+
+  let convexUrl = isDev ? getConvexDevUrl() : getConvexProdUrl();
+
+  if (!convexUrl && !args.skipConvex) {
+    console.log("   No production deployment found. Will get URL after deploying backend.");
+  } else if (!convexUrl && isDev) {
+    console.error("");
+    console.error("❌ Could not determine dev Convex URL");
+    console.error("   Make sure 'npx convex dev' is running and .env.local contains CONVEX_URL");
+    process.exit(1);
+  } else if (convexUrl) {
+    console.log(`   ✓ ${convexUrl}`);
+  }
+
+  // Step 2: Build frontend
+  if (!args.skipBuild) {
+    console.log("");
+    console.log("Step 2: Building frontend...");
+
+    // If we don't have a URL yet, we need to deploy Convex first to get it
+    if (!convexUrl && !args.skipConvex) {
+      console.log("   Deploying Convex backend first to get production URL...");
+      console.log("");
+
+      const convexResult = spawnSync("npx", ["convex", "deploy"], {
+        stdio: "inherit",
+      });
+
+      if (convexResult.status !== 0) {
+        console.error("");
+        console.error("❌ Convex deployment failed");
+        process.exit(1);
+      }
+
+      // Now get the URL
+      convexUrl = getConvexProdUrl();
+      if (!convexUrl) {
+        console.error("");
+        console.error("❌ Could not get production Convex URL after deployment");
+        process.exit(1);
+      }
+      console.log("");
+      console.log(`   ✓ Production URL: ${convexUrl}`);
+      args.skipConvex = true; // Already deployed
+    }
+
+    if (!convexUrl) {
+      console.error("");
+      console.error("❌ Could not determine Convex URL for build");
+      console.error("   Run 'npx convex deploy' first or remove --skip-convex");
+      process.exit(1);
+    }
+
+    console.log(`   Building with VITE_CONVEX_URL=${convexUrl}`);
+    console.log("");
+
+    const buildResult = spawnSync("npm", ["run", "build"], {
+      stdio: "inherit",
+      env: { ...process.env, VITE_CONVEX_URL: convexUrl },
+    });
+
+    if (buildResult.status !== 0) {
+      console.error("");
+      console.error("❌ Build failed");
+      process.exit(1);
+    }
+
+    console.log("");
+    console.log("   ✓ Build complete");
+  } else {
+    console.log("");
+    console.log("Step 2: Skipping build (--skip-build)");
+  }
+
+  // Step 3: Deploy Convex backend
+  if (!args.skipConvex) {
+    console.log("");
+    console.log("Step 3: Deploying Convex backend...");
+    console.log("");
+
+    const convexResult = spawnSync("npx", ["convex", "deploy"], {
+      stdio: "inherit",
+    });
+
+    if (convexResult.status !== 0) {
+      console.error("");
+      console.error("❌ Convex deployment failed");
+      process.exit(1);
+    }
+
+    console.log("");
+    console.log("   ✓ Convex backend deployed");
+  } else {
+    console.log("");
+    console.log("Step 3: Skipping Convex deployment (--skip-convex or already deployed)");
+  }
+
+  // Step 4: Deploy static files
+  console.log("");
+  console.log("Step 4: Deploying static files to Convex storage...");
+
+  const distDir = resolve(args.dist);
+
+  if (!existsSync(distDir)) {
+    console.error("");
+    console.error(`❌ Dist directory not found: ${distDir}`);
+    console.error("   Run build first or check --dist path");
+    process.exit(1);
+  }
+
+  const staticDeploySuccess = await uploadToConvexStorage(distDir, args.component, args.cdn, !isDev);
+
+  if (!staticDeploySuccess) {
+    console.error("");
+    console.error("❌ Static file upload failed");
+    process.exit(1);
+  }
+
+  // Done!
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  console.log("");
+  console.log("═══════════════════════════════════════════════════════════");
+  console.log(`✨ Deployment complete! (${duration}s)`);
+  console.log("");
+
+  // Show Convex site URL
+  try {
+    const envFlag = isDev ? "" : "--prod";
+    const result = execSync(`npx convex env get CONVEX_CLOUD_URL ${envFlag}`, {
+      stdio: "pipe",
+      encoding: "utf-8",
+    });
+    const cloudUrl = result.trim();
+    if (cloudUrl && cloudUrl.includes(".convex.cloud")) {
+      const siteUrl = cloudUrl.replace(".convex.cloud", ".convex.site");
+      console.log(`Frontend: ${siteUrl}`);
+    }
+  } catch {
+    // Ignore
+  }
+
+  console.log("");
+}
+
+main().catch((error) => {
+  console.error("Deployment failed:", error);
+  process.exit(1);
+});

package/src/cli/index.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * CLI for Convex Static Hosting
+ *
+ * Commands:
+ *   deploy              One-shot deployment (Convex backend + static files)
+ *   upload              Upload static files to Convex storage
+ *   next-build          Build Next.js app and prepare for Convex deployment
+ *   init                Print setup instructions
+ */
+
+const command = process.argv[2];
+
+async function main() {
+  switch (command) {
+    case "setup":
+      await import("./setup.js");
+      break;
+
+    case "deploy":
+      // Pass remaining args to deploy command
+      process.argv.splice(2, 1);
+      await import("./deploy.js");
+      break;
+
+    case "upload":
+      // Pass remaining args to upload command
+      process.argv.splice(2, 1);
+      await import("./upload.js");
+      break;
+
+    case "next-build":
+      // Pass remaining args to next-build command
+      process.argv.splice(2, 1);
+      await import("./next-build.js");
+      break;
+
+    case "init":
+      printInitInstructions();
+      break;
+
+    case "--help":
+    case "-h":
+    case undefined:
+      printHelp();
+      break;
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log("");
+      printHelp();
+      process.exit(1);
+  }
+}
+
+function printHelp() {
+  console.log(`
+Convex Static Hosting CLI
+
+Usage:
+  npx @convex-dev/static-hosting <command> [options]
+
+Commands:
+  setup               Interactive setup wizard (creates files, configures deployment)
+  deploy              One-shot deployment (Convex backend + static files)
+  upload              Upload static files to Convex storage
+  next-build          Build Next.js app and prepare for Convex deployment
+  init                Print setup instructions for integration
+
+Examples:
+  # Interactive setup (recommended for first-time users)
+  npx @convex-dev/static-hosting setup
+
+  # One-shot deployment
+  npx @convex-dev/static-hosting deploy
+
+  # Upload only (no Convex backend deploy)
+  npx @convex-dev/static-hosting upload --build --prod
+
+Run '<command> --help' for more information on a specific command.
+`);
+}
+
+function printInitInstructions() {
+  console.log(`
+📦 Convex Static Hosting
+
+Quick Start:
+  npx @convex-dev/static-hosting setup    # Interactive setup wizard
+
+For LLMs:
+  Read INTEGRATION.md in this package for complete integration instructions
+
+Manual Setup:
+  See README.md at https://github.com/get-convex/static-hosting#readme
+
+This component hosts your static files in Convex storage and serves them via HTTP actions.
+`);
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});