Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hyperauth.dev/llms.txt

Use this file to discover all available pages before exploring further.

Prerequisites
  • Node.js 18 or higher
  • Bun (for compiling WASM artifacts)
  • The wrangler CLI if running the Vault Worker locally

​
Project layout

A typical HyperAuth app has three moving parts:
ComponentRuntimeNotes
Your React appVite or your preferred bundlerImports @hyperauth/sdk and @hyperauth/react
Stateless signerenclave.wasm inside a Dedicated WorkerOne per browser tab
Stateful vaultvault.wasm inside a SharedWorkerOne per origin
The signer and vault are loaded by HyperAuthProvider from /enclave.wasm and /vault.wasm by default. You can serve them from your app’s public/ directory in development, or from a CDN such as Cloudflare R2 in production.

​
Compile the WASM artifacts

From the monorepo root: 
bun run compile:wasm
This emits core/enclave/dist/enclave.wasm and core/vault/dist/vault.wasm. Copy them into your app’s public/ directory before starting the dev server: 
cp core/enclave/dist/enclave.wasm apps/my-app/public/
cp core/vault/dist/vault.wasm apps/my-app/public/
Wire predev and prebuild hooks in your app’s package.json to copy the binaries automatically each time you run vite or build for production.

​
Start the dev server

Run your app’s dev script: 
npm run dev
The default Vite URL is http://localhost:5173. The SDK’s defaults (/enclave.wasm, /vault.wasm, /api/bundler, /api/indexer) resolve against the same origin, so a proxy to the Vault Worker on port 8787 works without any additional configuration.

​
Run the Vault Worker locally

If your client needs the Vault Worker’s HTTP API (e.g. for /api/sessions or /api/dids), run it under wrangler: 
cd apps/vault
wrangler dev
The dev server starts on http://localhost:8787. Add the secrets your local Worker requires to apps/vault/.dev.vars:
apps/vault/.dev.vars
PIMLICO_API_KEY=your_key
TWILIO_ACCOUNT_SID=your_sid
RESEND_API_KEY=your_key
ATTESTATION_SIGNING_KEY=your_key
Never commit .dev.vars. It’s gitignored by default in the starter Worker template.
If you’re editing this docs site, the Mintlify CLI can check for broken links: 
mint broken-links

​
Troubleshooting

The most common cause is the WASM file is missing from public/. Run bun run compile:wasm and copy the artifacts as shown above. If the file is present, check that your dev server is serving it with Content-Type: application/wasm — Vite handles this automatically; other bundlers may need a plugin.
SharedWorker is not supported in some browsers (notably Safari on iOS prior to iOS 16). The SDK detects this and surfaces an error status via the provider. Test in Chrome or Firefox first to rule out platform-specific behavior.
By default the vault auto-locks after 5 minutes of inactivity, and a page reload always loses in-memory state. Persist the encrypted database via client.setAutoLockCallback or call client.exportVault({ password }) and store the result yourself. See Vault Management for the full workflow.