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.

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
  • 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 configured through Supabase the same way as Google, but with credentials from GitHub Developer Settings instead of Google Cloud.

Step 1: Create a GitHub OAuth App

  1. Go to GitHub → Settings → Developer settings → OAuth Apps
  2. Click New OAuth App
  3. Set your homepage URL to your public site, for example: https://yourdomain.com
  4. Set the callback URL to: https://<your-project>.supabase.co/auth/v1/callback
  5. Register the app and copy the Client ID and Client Secret

Step 2: Enable in Supabase

  1. In Supabase Dashboard → Authentication → Sign In / 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:

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

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 loops back without signing in — Re-check the GitHub OAuth callback URL and make sure the provider is enabled in Supabase

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",

Only configure one chat provider — if both are set, both widgets will load.

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.

integrationssupabasegooglegithubstriperesendmailguntawkvercel