Documentation / Ship & maintain
Deployment
Each product uses its own Hexclave project, Convex deployment, Cloudflare Worker, and GitHub configuration. Initialize the product and verify its local signed-in flow before enabling deployment. See getting started.
Configure GitHub Actions
The product's Checks and Deployment workflow runs checks and the OpenNext Worker build. Pull requests do not deploy. On main, configured backend sync runs after checks; Cloudflare deployment waits for that sync to succeed.
Required repository secrets:
| Secret | Purpose |
|---|---|
HEXCLAVE_SECRET_SERVER_KEY | Server operations in the selected Hexclave project |
CONVEX_DEPLOY_KEY | The configured development deployment's backend sync key |
CLOUDFLARE_API_TOKEN | A scoped token with permission to deploy Workers to your account |
CLOUDFLARE_ACCOUNT_ID | The target Cloudflare account |
Public repository variables:
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_HEXCLAVE_PROJECT_ID | The single Hexclave project ID for the frontend and both server environments |
NEXT_PUBLIC_CONVEX_URL | The configured Convex client URL |
CONVEX_SYNC_ENABLED | Set to true after configuring backend credentials |
CLOUDFLARE_DEPLOY_ENABLED | Set to true after configuring Worker credentials and trusted auth domains |
HEXCLAVE_CONFIG_SYNC_ENABLED | Set to true when branch configuration sync is intended |
Public npm dependencies install without package-read tokens. Optional PIXELARTICONS_LICENSE_KEY can be supplied as an Actions secret for a product's own licensed icon installation. The starter's default imports use free icons.
Keep backend and Worker configuration aligned
Before pushing backend functions, CI runs scripts/sync-convex-env.mjs to install HEXCLAVE_PROJECT_ID and the existing HEXCLAVE_SECRET_SERVER_KEY into Convex. Values pass through CLI stdin without being printed. The Worker deployment receives the same project ID and server key as runtime secrets; the Convex deploy key stays in the backend job.
Team administration and coordinated account deletion require this server key in Convex as well as the Worker. When rotating it, update the existing Actions secret and rerun the relevant deployment so both runtimes receive the replacement. Local bun run dev:mode uses the same environment-sync script.
Build and preview the Worker
Next.js runs on Cloudflare Workers through OpenNext. Product initialization sets the Worker name and its WORKER_SELF_REFERENCE service in wrangler.jsonc.
bunx wrangler login
bun run build:cloudflare
bun run preview:cloudflare
The Worker preview normally listens at http://localhost:8787. Public build values come from your configured environment. For local Workers preview, supply HEXCLAVE_PROJECT_ID and HEXCLAVE_SECRET_SERVER_KEY through an ignored .dev.vars file.
The build removes non-public values from OpenNext's generated environment module. Production receives server credentials through Worker secrets. Keep secrets out of NEXT_PUBLIC_* variables and static assets.
Deploy your application
The configured GitHub job installs the required Worker secrets. For a manual first deployment, configure those same secrets with Wrangler's secure interactive input:
bunx wrangler secret put HEXCLAVE_PROJECT_ID
bunx wrangler secret put HEXCLAVE_SECRET_SERVER_KEY
bun run deploy:cloudflare
HEXCLAVE_PROJECT_ID has the same value as NEXT_PUBLIC_HEXCLAVE_PROJECT_ID; it is not another service project. deploy:cloudflare builds before deploying and preserves existing runtime variables. Confirm the actual deployed URL in Wrangler's output.
Add the exact deployed origin to Hexclave's trusted domains through its dashboard. CLI OAuth login and the Actions token are separate credentials. Verify hosted sign-in returns to /app, account settings load, and a saved personal note returns after a reload.
Configure account services
Sync hexclave.config.ts for your intended project before verifying team creation, member/admin roles, user/team API keys, and account deletion. bun run sync:hexclave reads the current cloud branch first and preserves its email theme unless you explicitly supply HEXCLAVE_EMAIL_THEME_ID. Environment overrides remain service-owned; inspect them when a feature differs from local config.
Optional build variables NEXT_PUBLIC_PRODUCT_NAME and NEXT_PUBLIC_PRODUCT_DESCRIPTION override product branding. NEXT_PUBLIC_HEXCLAVE_STRIPE_PUBLISHABLE_KEY enables local card-update UI for the correct payment environment. Public configured offers can open hosted checkout without that optional key; enabling payments alone does not create purchase offers.
See accounts and teams for permissions, billing requirements, coordinated cleanup, and verification.
Prepare production services
The development command and supplied backend workflow target a development deployment. Before launching a production product, provision the intended production services, update public URLs and secrets, and adapt the backend workflow to use a production Convex key with convex deploy. Configure exact trusted domains and verify the full signed-in flow again.
Public pages are prerendered using the adapter's read-only static asset cache. Private account and application data come from authenticated APIs. ISR and on-demand revalidation require a writable cache before use.
Runtime publication and template releases do not deploy downstream applications. Each product controls its own rollout.