Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/eggarcia98/auth-backend/llms.txt

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

Prerequisites:

​
Overview

auth-backend includes a wrangler.toml configuration for deployment to Cloudflare Workers. Workers run on Cloudflare’s edge network and do not use a persistent Node.js process — environment variables are supplied as secrets rather than a .env file.
The wrangler.toml references src/index.ts as the Workers entry point, but this file does not exist in the repository. To deploy to Cloudflare Workers, you must create a src/index.ts that exports a Workers-compatible fetch handler using the Fastify app. The standard src/server.ts binds to a port and is not directly compatible with the Workers runtime.

​
wrangler.toml configuration

The project includes a wrangler.toml that configures the Workers deployment:
wrangler.toml
name = "auth-backend"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

[vars]
ENVIRONMENT = "development"

# Secrets (don't commit these!)
# Add via: wrangler secret put SECRET_NAME
# Required secrets:
# - SUPABASE_URL
# - SUPABASE_ANON_KEY
# - SUPABASE_SERVICE_ROLE_KEY
# - JWT_SECRET
# - FRONTEND_URL
# Optional (for OAuth):
# - GOOGLE_CLIENT_ID
# - GOOGLE_CLIENT_SECRET
# - APPLE_CLIENT_ID
# - APPLE_TEAM_ID
# - APPLE_KEY_ID
# - APPLE_PRIVATE_KEY

​
nodejs_compat flag

The compatibility_flags = ["nodejs_compat"] setting enables the Node.js compatibility layer in the Cloudflare Workers runtime. This polyfills core Node.js APIs (such as crypto, buffer, and stream) that packages like Fastify and Supabase depend on. Without this flag, many npm packages that target Node.js will throw errors at runtime.

​
Deploy to Cloudflare Workers

1

Install Wrangler

Wrangler is already listed as a dev dependency in package.json. Install it with:
pnpm install
Verify the installation:
npx wrangler --version
Then authenticate with your Cloudflare account:
npx wrangler login
This opens a browser window to authorize the CLI.
2

Configure secrets

Cloudflare Workers do not use .env files. Each environment variable must be added as a secret using wrangler secret put. Secrets are encrypted at rest and injected into the Worker at runtime.Add all required secrets:
# Required secrets
npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_ANON_KEY
npx wrangler secret put SUPABASE_SERVICE_ROLE_KEY
npx wrangler secret put JWT_SECRET
npx wrangler secret put FRONTEND_URL
Each command prompts you to paste the secret value. The value is never stored in plaintext.If you use Apple Sign-In, add these optional secrets as well:
# Optional — Apple Sign-In
npx wrangler secret put APPLE_CLIENT_ID
npx wrangler secret put APPLE_TEAM_ID
npx wrangler secret put APPLE_KEY_ID
npx wrangler secret put APPLE_PRIVATE_KEY
Google OAuth credentials are not required as backend environment variables — they are configured directly in your Supabase project under Authentication → Providers → Google.
To list secrets already configured for your Worker, run npx wrangler secret list.
3

Deploy the Worker

Deploy to Cloudflare’s global network:
npx wrangler deploy
Wrangler bundles src/index.ts and its dependencies, uploads the bundle, and prints the Worker URL:
Deployed auth-backend (VERSION) triggers:
  https://auth-backend.<your-subdomain>.workers.dev
To preview the Worker locally before deploying, run npx wrangler dev. This starts a local emulator at http://localhost:8787.

​
Required secrets reference

The following table lists every variable from .env.example and how to supply it in a Workers deployment:
VariableRequiredDescription
SUPABASE_URLYesYour Supabase project URL
SUPABASE_ANON_KEYYesSupabase anonymous (public) key
SUPABASE_SERVICE_ROLE_KEYYesSupabase service role key (admin access)
JWT_SECRETYesSecret used to sign JWTs (minimum 32 characters)
FRONTEND_URLYesAllowed CORS origin for the frontend
APPLE_CLIENT_IDNoApple Sign-In service ID
APPLE_TEAM_IDNoApple developer team ID
APPLE_KEY_IDNoApple Sign-In key ID
APPLE_PRIVATE_KEYNoApple Sign-In private key (PEM format)
ENVIRONMENT is set as a plain [vars] entry in wrangler.toml and does not need to be a secret.
Google OAuth credentials are not required as backend environment variables. They are configured in your Supabase dashboard under Authentication → Providers → Google.
The SUPABASE_SERVICE_ROLE_KEY grants full database access. Treat it as a sensitive credential and never expose it in client-side code or logs.

​
Differences from traditional Node.js deployment

Cloudflare Workers run in a V8 isolate, not a standard Node.js process. There are several important differences to be aware of:
AspectNode.js / DockerCloudflare Workers
RuntimeNode.js process (persistent)V8 isolate (stateless, per-request)
Environment variables.env file or --env-file flagwrangler secret put / [vars] in wrangler.toml
Entry pointdist/server.js (compiled output)src/index.ts (bundled by Wrangler)
Port bindingFastify binds to 0.0.0.0:8080No port binding — Workers respond to HTTP fetch events
File systemFull read/write accessNo file system access
Startup timeSeconds (cold start)Milliseconds (edge-optimized)
Node.js built-insNativePolyfilled via nodejs_compat flag
Cloudflare Workers do not support all Node.js APIs. Modules that rely on fs, child_process, net, or native addons will not work in the Workers runtime, even with nodejs_compat enabled. Verify all dependencies are Workers-compatible before deploying.
Workers have a CPU time limit per request (50ms on the free plan, 30 seconds on paid plans). Long-running operations such as heavy cryptography or large database queries may be interrupted.

​
Managing secrets across environments

Wrangler supports named environments (e.g., staging, production) defined in wrangler.toml. To add a secret to a specific environment, use the --env flag: 
npx wrangler secret put JWT_SECRET --env production
npx wrangler secret put JWT_SECRET --env staging
Secrets scoped to an environment are only available in that environment’s Worker deployment.

Build docs developers (and LLMs) love

Get started for freeTalk to us