init.d.ts

#!/usr/bin/env node
/**
 * Output integration instructions for LLMs.
 *
 * Usage:
 *   npx @convex-dev/static-hosting init
 */
declare const instructions = "\n# Convex Static Hosting - Integration Instructions\n\nYou are integrating the @convex-dev/static-hosting component into a Convex app.\nThis component enables hosting static files (React/Vite apps) directly on Convex.\n\n## What This Component Does\n\n- Stores static files in Convex storage\n- Serves files via HTTP actions with proper MIME types\n- Supports SPA routing (fallback to index.html)\n- Smart caching: hashed assets cached forever, HTML revalidates\n- ETag support for efficient cache revalidation\n- Live reload notifications when new deployments happen\n\n## Files to Create/Modify\n\n### 1. convex/convex.config.ts (create or modify)\n\n```typescript\nimport { defineApp } from \"convex/server\";\nimport selfHosting from \"@convex-dev/static-hosting/convex.config\";\n\nconst app = defineApp();\napp.use(selfHosting);\n\nexport default app;\n```\n\n### 2. convex/staticHosting.ts (create)\n\n```typescript\nimport { components } from \"./_generated/api\";\nimport {\n  exposeUploadApi,\n  exposeDeploymentQuery,\n} from \"@convex-dev/static-hosting\";\n\n// Internal functions for secure uploads (only callable via CLI)\nexport const { generateUploadUrl, generateUploadUrls, recordAsset, recordAssets, gcOldAssets, listAssets } =\n  exposeUploadApi(components.selfHosting);\n\n// Public query for live reload notifications\nexport const { getCurrentDeployment } =\n  exposeDeploymentQuery(components.selfHosting);\n```\n\n### 3. convex/http.ts (create or modify)\n\n```typescript\nimport { httpRouter } from \"convex/server\";\nimport { registerStaticRoutes } from \"@convex-dev/static-hosting\";\nimport { components } from \"./_generated/api\";\n\nconst http = httpRouter();\n\n// Option A: Serve at root (if no other HTTP routes)\nregisterStaticRoutes(http, components.selfHosting);\n\n// Option B: Serve at /app/ prefix (recommended if you have API routes)\n// registerStaticRoutes(http, components.selfHosting, {\n//   pathPrefix: \"/app\",\n// });\n\n// Add other HTTP routes here if needed\n// http.route({ path: \"/api/webhook\", method: \"POST\", handler: ... });\n\nexport default http;\n```\n\n### 4. package.json scripts (add)\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"vite build\",\n    \"deploy:static\": \"npx @convex-dev/static-hosting upload --build --prod\"\n  }\n}\n```\n\nIMPORTANT: Use `--build` flag instead of running `npm run build` separately.\nThe `--build` flag ensures `VITE_CONVEX_URL` is set correctly for the target\nenvironment (production or dev). Running build separately uses .env.local which\nhas the dev URL.\n\n### 5. src/App.tsx (optional: add live reload banner)\n\n```typescript\nimport { UpdateBanner } from \"@convex-dev/static-hosting/react\";\nimport { api } from \"../convex/_generated/api\";\n\nfunction App() {\n  return (\n    <div>\n      {/* Shows banner when new deployment is available */}\n      <UpdateBanner\n        getCurrentDeployment={api.staticHosting.getCurrentDeployment}\n        message=\"New version available!\"\n        buttonText=\"Refresh\"\n      />\n      \n      {/* Rest of your app */}\n    </div>\n  );\n}\n```\n\nOr use the hook for custom UI:\n```typescript\nimport { useDeploymentUpdates } from \"@convex-dev/static-hosting/react\";\nimport { api } from \"../convex/_generated/api\";\n\nfunction App() {\n  const { updateAvailable, reload, dismiss } = useDeploymentUpdates(\n    api.staticHosting.getCurrentDeployment\n  );\n  \n  // Custom update notification UI\n}\n```\n\n## Deployment\n\n```bash\n# Login to Convex (first time)\nnpx convex login\n\n# Deploy Convex backend to production FIRST\nnpx convex deploy\n\n# Deploy static files to production\nnpm run deploy:static\n\n# Your app is now live at:\n# https://your-deployment.convex.site\n# (or https://your-deployment.convex.site/app/ if using path prefix)\n```\n\nFor development/testing:\n```bash\n# Push to dev environment\nnpx convex dev --once\n\n# Deploy static files to dev (omit --prod)\nnpx @convex-dev/static-hosting upload --build\n```\n\n## CLI Reference\n\n```bash\nnpx @convex-dev/static-hosting upload [options]\n\nOptions:\n  -d, --dist <path>        Path to dist directory (default: ./dist)\n  -c, --component <module> Module name where upload API is exposed \u2014 i.e. convex/<module>.ts (default: staticHosting)\n      --prod               Deploy to production Convex deployment\n      --dev                Deploy to dev deployment (default)\n  -b, --build              Run 'npm run build' with correct VITE_CONVEX_URL\n  -h, --help               Show help\n```\n\n## Important Notes\n\n1. The upload functions are INTERNAL - they can only be called via `npx convex run`, not from the public internet\n2. Static files are stored in the app's storage (not the component's) for proper isolation\n3. Hashed assets (e.g., main-abc123.js) get immutable caching; HTML files always revalidate\n4. The component supports SPA routing - routes without file extensions serve index.html\n5. Always use `--build` flag to ensure VITE_CONVEX_URL is set correctly for the target environment\n6. Deploy Convex backend (`npx convex deploy`) BEFORE deploying static files to production\n";
//# sourceMappingURL=init.d.ts.map