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-Template

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

2. Install Dependencies

npm install

All dependencies including Astro, Cloudflare adapter, and TypeScript are pre-configured.

3. Update Configuration

Update your wrangler.jsonc with your site name and deployment preferences. The @mindfulauth/core library handles session validation and middleware configuration 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:

• import.meta.env.DEV is true only when running npm run dev
• 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 the INTERNAL_API_KEY.

For Cloudflare Workers

Add your INTERNAL_API_KEY as a secret:

npx wrangler secret put INTERNAL_API_KEY
# Paste your tenant's internal API 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