Mindful Auth - Astro Setup Guide

1. Run npm command

This command will create a new Astro project using the Mindful Auth template.

npm create astro@latest -- --template Mindful-Auth/Mindful-Auth-Astro-6-Template

Github repository: https://github.com/Mindful-Auth/Mindful-Auth-Astro-6-Template

2. Install Dependencies

npm install

All dependencies are pre-configured in the template. For reference:

"dependencies": {
  "@astrojs/check": "^0.9.8",
  "@astrojs/cloudflare": "^13.1.3",
  "@mindfulauth/astro": "^4.0.0",
  "astro": "^6.0.8"
},
"devDependencies": {
  "@cloudflare/workers-types": "^4.20260317.1",
  "@types/node": "^25.5.0",
  "typescript": "^6.0.2",
  "wrangler": "^4.76.0"
}

3. Update Configuration

Update your wrangler.jsonc with your site name and deployment preferences. The @mindfulauth/astro library handles session validation, middleware configuration, and authentication components automatically.

4. Configure Secrets

For rapid local development, you can run npm run dev on localhost without registering a tenant in Mindful Auth. The middleware automatically detects development mode and injects a mock session.

npm run dev
# Visit http://localhost:4321/dev-user-123/dashboard (with mock session)

How it works:

Middleware bypasses Mindful Auth validation on localhost
Mock session is injected with recordId extracted from the URL
Automatically disabled in production - npm run build sets DEV=false

What you can test locally:

✅ Protected page layouts and components
✅ UI/UX changes and styling
✅ Component functionality with mock user sessions
✅ Routing and navigation between pages
✅ Live editing with hot module reload

What you CANNOT test locally:

❌ Login/registration flows
❌ Password reset and email verification
❌ 2FA setup and verification
❌ Any Mindful Auth authentication endpoints

Why? Localhost is intentionally not allowed in Mindful Auth to avoid cluttering the production data. Authentication testing requires deploying to a domain registered in Mindful Auth.

Production deployments always use npm run build, which disables development mode automatically.

Production Deployment

⚠️ For production deployment, you must register your domain with Mindful Auth and configure MAUTH_SITE_KEY.

For Cloudflare Workers

Add your MAUTH_SITE_KEY as a secret:

npx wrangler secret put MAUTH_SITE_KEY
# Paste your tenant's site key when prompted

Or add it via the Cloudflare dashboard: Workers & Pages → Your Worker → Settings → Variables and Secrets

5. Deploy

npm run build
npm run preview  # Test production build locally

# Deploy to Cloudflare Workers
npx wrangler deploy