MantleKit
Back to Knowledge Base

Integrations

Complete setup guide for database, auth, payments, email, chat, and hosting

MantleKit integrates with several third-party services. This guide covers setting up each one in detail, including common pitfalls and troubleshooting tips.

Database (Supabase)

Supabase provides a hosted PostgreSQL database with built-in auth, real-time subscriptions, and a generous free tier (500MB storage, 50,000 monthly active users).

Creating Your Project

  1. Sign up at supabase.com — the free tier is more than enough to get started
  2. Click New Project and choose a name, database password, and region (pick the one closest to your users)
  3. Wait for the project to provision (usually under a minute)

Finding Your API Keys

Go to Project Settings → API (or Data API on newer dashboards):

  • Project URL — looks like https://<project-id>.supabase.co. This is your NEXT_PUBLIC_SUPABASE_URL
  • Anon/Publishable Key — safe for client-side use. This is your NEXT_PUBLIC_SUPABASE_ANON_KEY
  • Service Role Key — has full access, bypasses RLS. Keep this secret and server-side only. This is your SUPABASE_SERVICE_ROLE_KEY

All three are on the same page. You may need to click "Reveal" for the service role key.

You should also set:

  • NEXT_PUBLIC_SITE_URL to your final public domain, for example https://yourdomain.com

This keeps MantleKit's canonical URLs, Open Graph tags, and transactional links pointing at the correct site.

Running the Database Setup

MantleKit includes a unified SQL script that creates all required tables:

  1. In Supabase Dashboard, go to SQL Editor
  2. Open supabase/setup.sql from your project
  3. Paste the entire contents and click Run

This creates:

  • subscriptions table with RLS policies
  • webhook_events table for idempotency
  • products and orders tables for ecommerce
  • licence_keys table for CLI download gating
  • blog_comments, blog_comment_votes, and blog_likes tables for blog social features
  • profiles admin roles
  • teams, team_memberships, and calendar_events for internal workspaces
  • comment_moderation_settings for configurable comment review rules
  • analytics_events for the lightweight analytics dashboard
  • 5 example seed products

The script is idempotent — you can run it multiple times safely.

Configuring URL Redirects

This step is critical for auth to work in production:

  1. Go to Authentication → URL Configuration
  2. Set Site URL to your production domain (e.g. https://yourdomain.com)
  3. Under Redirect URLs, add:
    • https://yourdomain.com/** (production)
    • http://localhost:3000/** (local development)

Without this, confirmation emails and OAuth logins will redirect to localhost instead of your live site.

Email Templates

Supabase sends confirmation and password reset emails using built-in templates. To customise them:

  1. Go to Authentication → Email Templates
  2. Edit the Confirm Signup and Reset Password templates
  3. The {{ .ConfirmationURL }} variable uses the Site URL you configured above

For production, consider setting up a custom SMTP server in Project Settings → Auth → SMTP Settings so emails come from your domain instead of Supabase's default sender.

Authentication

MantleKit supports multiple auth methods via Supabase Auth. Enable them in your Supabase Dashboard under Authentication → Providers.

Email/Password

Enabled by default in most Supabase projects. Users sign up with an email and password, then receive a confirmation email. No additional setup required beyond configuring your Site URL (see above).

Google OAuth

Google OAuth lets users sign in with their Google account in one click.

Step 1: Create Google OAuth Credentials

  1. Go to Google Cloud Console
  2. Create a new project (or select an existing one)
  3. Navigate to APIs & Services → Credentials
  4. Click Create Credentials → OAuth client ID
  5. Select Web application as the application type
  6. Under Authorized redirect URIs, add: 
    https://<your-project>.supabase.co/auth/v1/callback
    Replace <your-project> with your Supabase project reference ID.
  7. Click Create and note the Client ID and Client Secret

Step 2: Configure OAuth Consent Screen

If prompted, configure the OAuth consent screen:

  1. Go to APIs & Services → OAuth consent screen
  2. Choose External user type
  3. Fill in the required fields: App name, user support email, developer email
  4. Add scopes: email and profile
  5. Save — you don't need to submit for verification unless you're launching to more than 100 users

Step 3: Enable in Supabase

  1. In Supabase Dashboard → Authentication → Providers → Google
  2. Toggle Google on
  3. Paste in your Client ID and Client Secret
  4. Save

Step 4: Verify in MantleKit

Make sure google: true is set in mantle.config.ts under authMethods:

authMethods: {
  emailPassword: true,
  google: true,
  github: true,
},

GitHub OAuth

GitHub OAuth is a great fit for dev-focused products and agencies.

Step 1: Create a GitHub OAuth App

  1. Go to GitHub Developer Settings
  2. Click OAuth Apps → New OAuth App
  3. Fill in:
    • Application name — your product name
    • Homepage URL — your production site
    • Authorization callback URL: https://<your-project>.supabase.co/auth/v1/callback
  4. Click Register application
  5. Copy the Client ID
  6. Generate and copy a Client Secret

Step 2: Enable in Supabase

  1. In Supabase Dashboard → Authentication → Providers → GitHub
  2. Toggle GitHub on
  3. Paste in your Client ID and Client Secret
  4. Save

Step 3: Verify in MantleKit

Make sure github: true is set in mantle.config.ts under authMethods.

Troubleshooting Auth

  • Confirmation email links to localhost — Update your Site URL in Supabase (see Database section above)
  • Google login shows "Error 400: redirect_uri_mismatch" — Double-check the authorized redirect URI in Google Cloud Console matches your Supabase callback URL exactly
  • "Provider not enabled" error — The auth method isn't toggled on in Supabase Authentication → Providers
  • GitHub login isn't showing — Make sure github: true is enabled in mantle.config.ts and the GitHub provider is toggled on in Supabase

AI Chat

MantleKit includes a dashboard AI assistant. It supports three providers:

  • OpenAI
  • Anthropic
  • OpenRouter

The AI assistant lives inside the admin dashboard and uses your configured provider plus a MantleKit-aware system prompt so it understands the current project setup better than a blank chatbot shell.

Required Environment Variables

The two most important variables are:

AI_PROVIDER=openai
AI_MODEL=gpt-4.1-mini

Then add the API key for the provider you want to use.

OpenAI

OpenAI is the default provider. If you do not set AI_PROVIDER, MantleKit falls back to OpenAI automatically.

AI_PROVIDER=openai
OPENAI_API_KEY=your-openai-api-key
AI_MODEL=gpt-4.1-mini

If you omit AI_MODEL, MantleKit still defaults to a sensible OpenAI model.

Anthropic

To use Anthropic:

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key
AI_MODEL=claude-sonnet-4-5

If you omit AI_MODEL, MantleKit defaults to claude-sonnet-4-5 for Anthropic.

OpenRouter

To use OpenRouter:

AI_PROVIDER=openrouter
OPENROUTER_API_KEY=your-openrouter-api-key
AI_MODEL=openai/gpt-4.1-mini

If you omit AI_MODEL, MantleKit uses a sensible OpenRouter default.

Where To Add These

Add the AI variables to your local environment file:

.env.local

For production, add the same variables to your hosting platform environment settings.

How MantleKit Chooses A Provider

The logic is simple:

  • If AI_PROVIDER=anthropic, it uses ANTHROPIC_API_KEY
  • If AI_PROVIDER=openrouter, it uses OPENROUTER_API_KEY
  • Otherwise, it uses OpenAI and expects OPENAI_API_KEY

If the provider is set correctly but the matching API key is missing, the dashboard AI will fail with a provider key error.

Troubleshooting AI Chat

  • AI chat says the provider key is missing — You set AI_PROVIDER, but not the matching API key
  • You only set OPENAI_API_KEY — That is fine; OpenAI is the default provider
  • Anthropic isn't being used — Make sure AI_PROVIDER=anthropic, not just ANTHROPIC_API_KEY
  • OpenRouter isn't being used — Make sure AI_PROVIDER=openrouter
  • The model name seems ignored — Check AI_MODEL spelling and restart your dev server after changing env vars

Payment Providers

MantleKit supports three payment providers. You choose one during setup via the CLI. All three charge per-transaction only — there are no monthly fees.

Stripe

Stripe is the most widely used payment provider and the recommended default.

Setting Up Stripe

  1. Create a Stripe account — start in test mode
  2. Go to Developers → API keys to find your Secret Key (sk_test_...)
  3. Create products and prices matching your tiers:
    • Go to Products → Add product
    • Create a product for each tier with the appropriate price
    • Note the Price ID (price_...) for each

Setting Up Webhooks

Webhooks let Stripe notify your app when payments succeed, subscriptions change, etc.

  1. Go to Developers → Webhooks → Add endpoint
  2. Set the endpoint URL to https://yourdomain.com/api/webhooks/stripe
  3. Select these events:
    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.payment_succeeded
    • invoice.payment_failed
  4. Click Add endpoint and copy the Signing Secret (whsec_...)

Environment Variables

Add to your .env.local:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Configuration

Update mantle.config.ts with your actual Stripe price IDs:

stripePriceIds: {
  monthly: "price_abc123",
  yearly: "price_def456",
},

Going Live

When you're ready for production:

  1. Toggle off test mode in the Stripe dashboard
  2. Replace test API keys with live keys in your environment variables
  3. Create a new webhook endpoint with your production URL
  4. Update the webhook secret in your environment

Lemon Squeezy

Lemon Squeezy is a merchant of record — they handle tax, compliance, and billing on your behalf.

  1. Create a Lemon Squeezy account
  2. Create a Store and add your products
  3. Get your API key from Settings → API
  4. Set up a webhook:
    • Go to Settings → Webhooks
    • Endpoint URL: https://yourdomain.com/api/webhooks/lemon-squeezy
    • Select relevant events (subscription created, updated, cancelled)
  5. Add to your environment: 
    LEMONSQUEEZY_API_KEY=your-api-key
LEMONSQUEEZY_STORE_ID=your-store-id
LEMONSQUEEZY_WEBHOOK_SECRET=your-webhook-secret

Polar

Polar is designed for open source and developer tools.

  1. Create a Polar account
  2. Create an organisation and add your products
  3. Get your Access Token from Settings
  4. Set up a webhook:
    • Endpoint URL: https://yourdomain.com/api/webhooks/polar
  5. Add to your environment: 
    POLAR_ACCESS_TOKEN=your-access-token
POLAR_WEBHOOK_SECRET=your-webhook-secret
POLAR_ORGANIZATION_ID=your-org-id

Testing Payments Locally

To test webhooks locally during development, use a tunnel to expose your local server:

# Using cloudflared (free, no account needed)
cloudflared tunnel --url http://localhost:3000

This gives you a temporary public URL. Use it as your webhook endpoint in test mode.

Email Providers

MantleKit uses email for transactional messages: welcome emails, password resets, purchase confirmations, and contact form submissions. Both providers offer generous free tiers.

Resend

Resend offers 3,000 emails/month free — enough for most projects.

  1. Create a Resend account
  2. Go to Domains → Add Domain
  3. Add the DNS records Resend provides (usually a TXT and MX record) to your DNS provider
  4. Wait for verification (can take a few minutes to an hour)
  5. Get your API key from API Keys → Create API Key
  6. Add to your environment: 
    RESEND_API_KEY=re_...
  7. Update mantle.config.ts: 
    emailProvider: "resend",
email: {
  from: "YourApp <noreply@yourdomain.com>",
  contactTo: "support@yourdomain.com",
},

Mailgun

Mailgun offers 1,000 emails/month free.

  1. Create a Mailgun account
  2. Go to Sending → Domains → Add New Domain
  3. Add the DNS records Mailgun provides
  4. Wait for domain verification
  5. Get your API key from Settings → API Keys
  6. Add to your environment: 
    MAILGUN_API_KEY=your-api-key
MAILGUN_DOMAIN=mg.yourdomain.com

Brevo (formerly Sendinblue)

Brevo offers 300 emails/day free (~9,000/month) — the most generous free tier for transactional email.

  1. Create a Brevo account
  2. Go to Settings → SMTP & API → API Keys
  3. Create a new API key
  4. Add and verify your sending domain under Settings → Senders & Domains
  5. Add to your environment: 
    BREVO_API_KEY=xkeysib-...
  6. Set in mantle.config.ts: 
    emailProvider: "brevo",

Email Not Arriving?

  • Check spam/junk folders — new sending domains often trigger spam filters initially
  • Verify DNS records — all providers show verification status in their dashboard
  • Check the "from" address — it must match your verified domain
  • Review Supabase SMTP — if auth emails aren't arriving, set up custom SMTP in Supabase using your email provider's credentials

Chat Support

MantleKit supports Tawk.to for the public chat widget. Configure it in mantle.config.ts and the widget appears automatically on all pages.

Tawk.to (100% Free)

Tawk.to is completely free — no paid tiers, no per-seat charges, unlimited agents.

  1. Create a Tawk.to account
  2. Add your website as a new property
  3. Go to Administration → Channels → Chat Widget
  4. Find your embed script — it contains your Property ID and Widget ID in the URL: 
    https://embed.tawk.to/PROPERTY_ID/WIDGET_ID
    For example: https://embed.tawk.to/69c91f1e0330fc1c37baef53/1jksq343q
  5. Set in mantle.config.ts: 
    tawkPropertyId: "69c91f1e0330fc1c37baef53",
tawkWidgetId: "1jksq343q",

Make sure both Tawk identifiers are set together so the widget can load correctly.

Hosting (Vercel)

Vercel is the recommended hosting platform. Their free Hobby plan is enough for most projects.

Initial Deployment

  1. Push your project to a Git repository (GitHub, GitLab, or Bitbucket)
  2. Go to vercel.com/new
  3. Import your repository
  4. Vercel auto-detects Next.js — no custom build configuration needed
  5. Click Deploy

Environment Variables

Before your first deploy (or immediately after), add all required environment variables:

  1. Go to your project → Settings → Environment Variables
  2. Add each variable from your .env.local file
  3. Make sure to set them for Production, Preview, and Development as needed

At minimum you need:

  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY
  • Your payment provider keys
  • Your email provider API key

Custom Domain

  1. Go to Settings → Domains
  2. Add your domain name
  3. Vercel will show you the DNS records to add:
    • A record: @ → 76.76.21.21
    • CNAME record: www → cname.vercel-dns.com
  4. Add these records in your DNS provider (or Vercel if they manage your DNS)
  5. SSL certificates are provisioned automatically once DNS propagates

DNS propagation can take anywhere from a few minutes to a few hours. If you see a certificate error, wait and try again.

Continuous Deployment

Every push to your main branch triggers an automatic production deployment. Pull requests get preview deployments with unique URLs — great for testing changes before merging.

Troubleshooting Vercel

  • Build fails with ECONNRESET — Transient network error. Just click Redeploy
  • Environment variable not found — Make sure it's added for the correct environment (Production vs Preview)
  • DNS certificate error — Wait for DNS propagation. Try removing and re-adding the domain if it persists
  • npm warn deprecated — These are warnings from transitive dependencies, not errors. They won't affect your build

Alternative Hosting

While Vercel is recommended, MantleKit works on any platform that supports Node.js:

  • Railway — Simple deploy from Git, $5/month hobby plan
  • Fly.io — Edge deployment, free tier available
  • DigitalOcean App Platform — From $5/month
  • AWS Amplify — If you're already in the AWS ecosystem
  • Self-hosted — Run next build && next start on any Node.js server

For non-Vercel platforms, you may need to configure build commands and output directories manually. The default Next.js settings (next build, .next output) work everywhere.

integrationssupabaseaigooglestriperesendmailguntawkvercel