---
name: bijection-static-hosting
description: "Evaluate and integrate the Static Hosting component with Bijection."
---

# Static Hosting

Static application hosting

- Package: @bijectionhq/static-hosting
- Category: Storage
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/static-hosting/tree/32688ca55039d4af2058238aa8442065a1d7b863
- Upstream: https://github.com/convex/static-hosting/tree/5d9992c25a8dadbe7454478e9b746636c7e97dec
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/static-hosting

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/static-hosting.git
cd static-hosting
git checkout 32688ca55039d4af2058238aa8442065a1d7b863
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/static-hosting. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Static-Hosting. Follow the installation and configuration steps exactly.

# Static-Hosting

## Instructions

Static-Hosting enables developers to serve React/Vite apps directly from Convex without external hosting providers. It uses Convex HTTP actions to serve files from Convex storage, with automatic SPA fallback for client-side routing, smart caching for hashed assets, and garbage collection of old deployments. The upload API uses internal functions for security, ensuring only authenticated CLI users can deploy files.

### Installation

```bash
npm install @convex-dev/static-hosting
```

Current npm version: `@convex-dev/static-hosting@0.2.1`

## Use cases

- **Deploy full-stack apps with single backend**: Host your React frontend and Convex backend functions in one deployment, eliminating the need for separate hosting services like Vercel or Netlify
- **Prototype and demo apps quickly**: Skip external hosting setup during development and share working demos directly from your Convex deployment URL
- **Build internal tools and admin dashboards**: Serve company-internal React apps from Convex with built-in authentication integration and no external dependencies
- **Create self-contained SaaS applications**: Package your entire application stack into Convex components that include both backend logic and frontend assets
- **Implement live deployment notifications**: Use the deployment query hooks to show users when new versions are available and prompt for page refreshes

## How it works

The component integrates into your Convex app configuration and HTTP router using `registerStaticRoutes()` to serve files from Convex storage. During deployment, the CLI uploads your built assets to Convex storage via internal functions like `generateUploadUrl()` and `recordAsset()`, which are only accessible through authenticated `npx convex run` commands for security.

The HTTP actions serve files with intelligent caching - hashed assets from bundlers like Vite get long-term cache headers while HTML files use ETags for freshness. The `spaFallback` option automatically serves `index.html` for unmatched routes, enabling client-side routing in single-page applications.

Deployment uses either a one-shot `deploy` command that builds your frontend with the correct production `VITE_CONVEX_URL`, deploys the Convex backend, then uploads static files, or separate `upload` commands for more control. The component automatically garbage collects old deployment files to prevent storage bloat.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Static-Hosting is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fstatic-hosting)
- [GitHub repository](https://github.com/get-convex/static-hosting)
- [Live demo](https://github.com/get-convex/static-hosting/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/static-hosting)
- [Convex documentation](https://docs.convex.dev)