Hopp til innhold
PraxisLogg inn
Kunnskapsseksjoner

Optional providers and env

How env-gated providers work; exact variables, where to set them, and how to verify activation.

envoptional-providersconfiguration
På denne siden

Optional providers activate from environment variables and Worker bindings. With their configuration absent, the starter uses an inactive or local adapter. packages/env/src/server.ts declares the variables and production config audit; BETTER_AUTH_SECRET and BETTER_AUTH_URL remain required for deployed auth.

Configure a provider

Use root .env for the web dev server, each Worker's .dev.vars for direct Wrangler development, and the deployment shell environment for Alchemy. alchemy.run.ts forwards declared variables and provisions the required bindings. Restart development processes after changing configuration.

ProviderConfigurationWithout configuration
Cloudflare EmailCLOUDFLARE_EMAIL_FROM plus an EMAIL bindingLog dispatcher
TurnstileTURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEYSign-up has no challenge
GitHub sign-inGITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETNo GitHub button
Google sign-inGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETNo Google button
Workers AIWORKERS_AI_ENABLED=true plus an AI bindingTries the next assistant provider
OpenAI-compatible assistantOPENAI_API_KEY; optional OPENAI_BASE_URL, OPENAI_MODEL_IDMock assistant
Workspace exportWORKSPACE_EXPORT_BUCKET, API_PUBLIC_URLD1-backed export actions unavailable
StripeSTRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_ID_TEAM; optional STRIPE_PRICE_ID_ENTERPRISEPlan display and local entitlement checks remain available
SentrySENTRY_DSNNo error export to Sentry
PostHogPOSTHOG_KEY; optional POSTHOG_HOSTNo PostHog capture
OTLPOTEL_EXPORTER_OTLP_ENDPOINTNo OTLP export

Verify activation

  • Email: send an invitation on a deployed stack and inspect delivery history. Local log delivery does not prove Cloudflare sending works.
  • Turnstile: load /sign-up with both keys set. The widget should appear; missing or invalid challenge responses must be rejected. Verification outages fail closed.
  • Social sign-in: the configured provider's button appears on /sign-in. Complete a sign-in and inspect /account for the linked method.
  • Exports: request an archive as an owner, wait for its ready notification, then download it. Local D1 uses emulated R2 and Queues; the Seed adapter builds archives in memory.
  • Billing: the billing page offers configured provider actions to an owner or admin. See Stripe billing for setup and recovery.
  • Observability: see Sentry and PostHog for server and browser behavior.

Assistant provider order

selectAssistantLayer in packages/ai prefers enabled Workers AI, then an OpenAI-compatible provider, then the mock. The web assistant calls the capability through a server function; machine clients use the API Worker:

curl -s https://<api-host>/assistant/answer \
  -H 'authorization: Bearer <api-token>' \
  -H 'content-type: application/json' \
  -d '{"workspaceSlug":"<slug>","question":"Hello"}'

A configured response reports provider: "workers-ai" or provider: "openai-compatible" and assistantConfigured: true.

Add a variable

Declare it in ServerEnv and classify it in the optional secret or plain key list in packages/env/src/server.ts. Alchemy forwarding and Worker string-binding types derive from those declarations. Add any required resource binding to the infrastructure configuration.